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.

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_binarytrue,则 @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),则调用线程将被阻塞,直到资源加载完成。


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

返回使用 load_threaded_requestpath 处启动的线程加载操作的状态。可能的返回值见 ThreadLoadStatus

可以通过 progress 可选地传递一个数组变量,并返回一个包含线程加载完成百分比的单元素的数组。


Error load_threaded_request(path: String, type_hint: String = "", use_sub_threads: bool = false, cache_mode: CacheMode = 1) 🔗

使用线程加载资源。如果 use_sub_threadstrue,将使用多个线程来加载资源,这会使加载更快,但可能会影响主线程(从而导致游戏降速)。

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


void remove_resource_format_loader(format_loader: ResourceFormatLoader) 🔗

取消注册给定的 ResourceFormatLoader


void set_abort_on_missing_resources(abort: bool) 🔗

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