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

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

描述

A singleton used to load resource files from the filesystem.

It uses the many ResourceFormatLoader classes registered in the engine (either built-in or from a plugin) to load files into memory and convert them to a format that can be used by the engine.

Note: You have to import the files into the engine first to load them using load. If you want to load Images at run-time, you may use Image.load. If you want to import audio files, you can use the snippet described in AudioStreamMP3.data.

Note: Non-resource files such as plain text files cannot be read using ResourceLoader. Use FileAccess for those files instead, and be aware that non-resource files are not exported by default (see notes in the FileAccess class description for instructions on exporting them).

教程

• 操作系统测试演示

方法

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

Returns the cached resource reference for the given path.

Note: If the resource is not cached, the returned Resource will be invalid.

---

PackedStringArray get_dependencies(path: String) 🔗

Returns the dependencies for the resource at the given path.

Note: The dependencies are returned with slices separated by ::. You can use String.get_slice to get their components.

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

Lists a directory (as example: "res://assets/enemies"), returning all resources contained within. The resource files are the original file names as visible in the editor before exporting.

---

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 = []) 🔗

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 ratio of completion of the threaded loading (between 0.0 and 1.0).

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

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