Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

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_binarytrue,则 @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_requestpath 处启动的线程加载操作的状态。可能的返回值见 ThreadLoadStatus

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


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

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

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


void remove_resource_format_loader ( ResourceFormatLoader format_loader )

取消注册给定的 ResourceFormatLoader


void set_abort_on_missing_resources ( bool abort )

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