ResourceLoader

继承： Object

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

描述

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

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

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

教程

• 操作系统测试演示

方法

枚举

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

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