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 ( ResourceFormatLoader format_loader, bool at_front=false )

bool

exists ( String path, String type_hint="" )

PackedStringArray

get_dependencies ( String path )

PackedStringArray

get_recognized_extensions_for_type ( String type )

int

get_resource_uid ( String path )

bool

has_cached ( String path )

Resource

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

Resource

load_threaded_get ( String path )

ThreadLoadStatus

load_threaded_get_status ( String path, Array progress=[] )

Error

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

void

remove_resource_format_loader ( ResourceFormatLoader format_loader )

void

set_abort_on_missing_resources ( bool abort )

枚举

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

CacheMode CACHE_MODE_REUSE = 1

CacheMode CACHE_MODE_REPLACE = 2

方法说明

void add_resource_format_loader ( ResourceFormatLoader format_loader, bool at_front=false )

注册一个新的 ResourceFormatLoader。ResourceLoader 将会按照 load 中的描述使用 ResourceFormatLoader。

对于用 GDScript 编写的 ResourceFormatLoader，此方法将隐式执行（详见 ResourceFormatLoader）。

bool exists ( String path, String type_hint="" )

返回给定路径 path 是否存在已识别的资源。

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

PackedStringArray get_dependencies ( String path )

返回位于给定路径 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 ( String type )

返回资源类型的已识别扩展名列表。

int get_resource_uid ( String path )

返回与一个给定资源路径关联的 ID，如果不存在此类 ID，则返回 -1。

bool has_cached ( String path )

返回给定 path 的缓存资源是否可用。

一旦引擎加载了资源，它将被缓存在内存中以加快访问速度，未来调用 load 方法将使用缓存版本。可以通过在具有相同路径的新资源上使用 Resource.take_over_path 来覆盖缓存资源。

Resource load ( String path, String type_hint="", CacheMode cache_mode=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。

Resource load_threaded_get ( String path )

返回由 load_threaded_request 加载的资源。

如果在加载线程完成之前调用此方法（即 load_threaded_get_status 不是 THREAD_LOAD_LOADED），则调用线程将被阻塞，直到资源加载完成。

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

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

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

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

使用线程加载资源。如果 use_sub_threads 为 true，将使用多个线程来加载资源，这会使加载更快，但可能会影响主线程（从而导致游戏降速）。

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

void remove_resource_format_loader ( ResourceFormatLoader format_loader )

取消注册给定的 ResourceFormatLoader。

void set_abort_on_missing_resources ( bool abort )

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