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 中描述的代码段。

教程¶

操作系统测试演示

方法¶

void	add_resource_format_loader(format_loader: ResourceFormatLoader, at_front: bool = false)
bool	exists(path: String, type_hint: 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)
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，即便对应的资源尚未保存（即仅存在于资源缓存中）。

PackedStringArray get_dependencies(path: String) 🔗

返回位于给定路径 path 的资源的依赖项。

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

for dep in ResourceLoader.get_dependencies(path):
    print(dep.get_slice("::", 0)) # 输出 UID。
    print(dep.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 来覆盖缓存资源。

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

Returns the resource loaded by load_threaded_request.

If this is called before the loading thread is done (i.e. load_threaded_get_status is not THREAD_LOAD_LOADED), the calling thread will be blocked until the resource has finished loading. However, it's recommended to use load_threaded_get_status to known when the load has actually completed.

ThreadLoadStatus load_threaded_get_status(path: String, progress: Array = []) 🔗

Returns the status of a threaded loading operation started with load_threaded_request for the resource at path. See ThreadLoadStatus for possible return values.

An array variable can optionally be passed via progress, and will return a one-element array containing the percentage of completion of the threaded loading.

Note: The recommended way of using this method is to call it during different frames (e.g., in Node._process, instead of a loop).

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

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