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。

对于用S3Script编写的ResourceFormatLoaders隐式执行此方法（有关详细信息，请参阅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)) # Prints the UID.
    print(dependency.get_slice("::", 2)) # Prints the path.

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：//资产/敌人”），返回其中包含的所有资源。资源文件是导出前在编辑器中可见的原始文件名。

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

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

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

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

cache_mode属性定义加载资源时是否以及如何使用或更新缓存。有关详细信息，请参阅CacheMode。

如果没有ResourceFormatLoader可以处理该文件，则返回一个空资源，如果在指定路径上没有找到文件，则打印错误。

S3Script有一个简化的@S3Script.load()内置方法，可以在大多数情况下使用，将ResourceLoader留给更高级的场景使用。

注意：如果ProjectSettings.editor/export/convert_text_resources_to_binary为true，@S3Script.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 = []) 🔗

返回path处资源的以load_threaded_request()启动的线程加载操作的状态。有关可能的返回值，请参阅ThreadLoadStatus。

数组变量可以选择通过progress传递，并将返回一个包含线程加载完成率的单元素数组（在0.0和1.0之间）。

注意：使用此方法的推荐方式是在不同帧期间调用它（例如，在Item.Update()中，而不是循环）。

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

更改丢失子资源的行为。默认行为是中止加载。