GFResourceLoadState¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/utilities/assets/gf_resource_load_state.gd - 模块：
Standard - 继承：
RefCounted - API：
public - 类别：值对象 (
value_object) - 首次版本：
7.0.0
资源加载状态与引用快照。 用于把资源键、路径、加载状态、进度、错误和弱/强引用模式收敛为统一状态对象。 它不发起 ResourceLoader 请求，也不规定资源包、下载或缓存策略。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 常量 | STATUS_UNREQUESTED |
const STATUS_UNREQUESTED: StringName = &"unrequested" |
| 常量 | STATUS_REQUESTED |
const STATUS_REQUESTED: StringName = &"requested" |
| 常量 | STATUS_LOADING |
const STATUS_LOADING: StringName = &"loading" |
| 常量 | STATUS_LOADED |
const STATUS_LOADED: StringName = &"loaded" |
| 常量 | STATUS_FAILED |
const STATUS_FAILED: StringName = &"failed" |
| 常量 | STATUS_RELEASED |
const STATUS_RELEASED: StringName = &"released" |
| 常量 | STATUS_STALE |
const STATUS_STALE: StringName = &"stale" |
| 常量 | REFERENCE_WEAK |
const REFERENCE_WEAK: StringName = &"weak" |
| 常量 | REFERENCE_STRONG |
const REFERENCE_STRONG: StringName = &"strong" |
| 属性 | resource_key |
var resource_key: StringName = &"" |
| 属性 | resource_path |
var resource_path: String = "" |
| 属性 | status |
var status: StringName = STATUS_UNREQUESTED: |
| 属性 | progress |
var progress: float = 0.0: |
| 属性 | error |
var error: String = "" |
| 属性 | reference_mode |
var reference_mode: StringName = REFERENCE_WEAK: |
| 属性 | metadata |
var metadata: Dictionary = {} |
| 方法 | configure |
func configure( p_resource_key: StringName, p_resource_path: String = "", options: Dictionary = {} ) -> GFResourceLoadState: |
| 方法 | set_status |
func set_status(p_status: StringName, options: Dictionary = {}) -> GFResourceLoadState: |
| 方法 | set_resource |
func set_resource(resource: Resource, options: Dictionary = {}) -> GFResourceLoadState: |
| 方法 | get_resource |
func get_resource() -> Resource: |
| 方法 | has_resource |
func has_resource() -> bool: |
| 方法 | clear_resource |
func clear_resource(options: Dictionary = {}) -> GFResourceLoadState: |
| 方法 | mark_requested |
func mark_requested(p_metadata: Dictionary = {}) -> GFResourceLoadState: |
| 方法 | mark_loading |
func mark_loading(p_progress: float = 0.0, p_metadata: Dictionary = {}) -> GFResourceLoadState: |
| 方法 | mark_loaded |
func mark_loaded(resource: Resource, p_metadata: Dictionary = {}) -> GFResourceLoadState: |
| 方法 | mark_failed |
func mark_failed(error_text: String, p_metadata: Dictionary = {}) -> GFResourceLoadState: |
| 方法 | mark_released |
func mark_released(p_metadata: Dictionary = {}) -> GFResourceLoadState: |
| 方法 | mark_stale |
func mark_stale(reason: String = "", p_metadata: Dictionary = {}) -> GFResourceLoadState: |
| 方法 | is_success |
func is_success() -> bool: |
| 方法 | is_terminal |
func is_terminal() -> bool: |
| 方法 | to_dictionary |
func to_dictionary() -> Dictionary: |
| 方法 | duplicate_state |
func duplicate_state() -> GFResourceLoadState: |
| 方法 | from_dictionary |
static func from_dictionary(data: Dictionary) -> GFResourceLoadState: |
常量¶
STATUS_UNREQUESTED¶
- API：
public - 首次版本：
7.0.0
尚未请求资源。
STATUS_REQUESTED¶
- API：
public - 首次版本：
7.0.0
已请求资源但尚未开始加载。
STATUS_LOADING¶
- API：
public - 首次版本：
7.0.0
资源正在加载。
STATUS_LOADED¶
- API：
public - 首次版本：
7.0.0
资源已加载。
STATUS_FAILED¶
- API：
public - 首次版本：
7.0.0
资源加载失败。
STATUS_RELEASED¶
- API：
public - 首次版本：
7.0.0
资源引用已释放。
STATUS_STALE¶
- API：
public - 首次版本：
7.0.0
资源状态已过期，需要调用方重新解析或加载。
REFERENCE_WEAK¶
- API：
public - 首次版本：
7.0.0
只保存弱引用。
REFERENCE_STRONG¶
- API：
public - 首次版本：
7.0.0
保存强引用，由状态对象持有资源。
属性¶
resource_key¶
- API：
public - 首次版本：
7.0.0
稳定资源键。
resource_path¶
- API：
public - 首次版本：
7.0.0
资源路径或解析后的路径。
status¶
- API：
public - 首次版本：
7.0.0
当前加载状态。
progress¶
- API：
public - 首次版本：
7.0.0
加载进度，范围 0 到 1。
error¶
- API：
public - 首次版本：
7.0.0
最近错误文本。
reference_mode¶
- API：
public - 首次版本：
7.0.0
资源引用模式。
metadata¶
- API：
public - 首次版本：
7.0.0
调用方元数据。
结构：
metadata: Dictionary for caller-defined resource state metadata.
方法¶
configure¶
- API：
public - 首次版本：
7.0.0
func configure( p_resource_key: StringName, p_resource_path: String = "", options: Dictionary = {} ) -> GFResourceLoadState:
配置资源加载状态。
参数：
| 名称 | 说明 |
|---|---|
p_resource_key |
稳定资源键。 |
p_resource_path |
资源路径。 |
options |
状态选项，支持 status、progress、error、reference_mode 和 metadata。 |
返回：当前状态。
结构：
options: Dictionary，可包含 status: StringName、progress: float、error: String、reference_mode: StringName、metadata: Dictionary。
set_status¶
- API：
public - 首次版本：
7.0.0
设置状态并按需合并 metadata。
参数：
| 名称 | 说明 |
|---|---|
p_status |
新状态。 |
options |
状态选项，支持 progress、error、metadata 和 clear_error。 |
返回：当前状态。
结构：
options: Dictionary，可包含 progress: float、error: String、metadata: Dictionary、clear_error: bool。
set_resource¶
- API：
public - 首次版本：
7.0.0
设置当前资源引用。
参数：
| 名称 | 说明 |
|---|---|
resource |
已加载资源；为空时会清除引用。 |
options |
引用选项，支持 reference_mode 和 metadata。 |
返回：当前状态。
结构：
options: Dictionary，可包含 reference_mode: StringName 和 metadata: Dictionary。
get_resource¶
- API：
public - 首次版本：
7.0.0
获取当前资源引用。
返回：当前资源；弱引用已释放时返回 null。
has_resource¶
- API：
public - 首次版本：
7.0.0
检查当前状态是否仍能取得资源。
返回：资源引用仍有效时返回 true。
clear_resource¶
- API：
public - 首次版本：
7.0.0
清除当前资源引用。
参数：
| 名称 | 说明 |
|---|---|
options |
清除选项，支持 status 和 metadata。 |
返回：当前状态。
结构：
options: Dictionary，可包含 status: StringName 和 metadata: Dictionary。
mark_requested¶
- API：
public - 首次版本：
7.0.0
标记资源已请求。
参数：
| 名称 | 说明 |
|---|---|
p_metadata |
调用方元数据。 |
返回：当前状态。
结构：
p_metadata: Dictionary merged into metadata.
mark_loading¶
- API：
public - 首次版本：
7.0.0
标记资源正在加载。
参数：
| 名称 | 说明 |
|---|---|
p_progress |
加载进度。 |
p_metadata |
调用方元数据。 |
返回：当前状态。
结构：
p_metadata: Dictionary merged into metadata.
mark_loaded¶
- API：
public - 首次版本：
7.0.0
标记资源已加载并保存引用。
参数：
| 名称 | 说明 |
|---|---|
resource |
已加载资源。 |
p_metadata |
调用方元数据。 |
返回：当前状态。
结构：
p_metadata: Dictionary merged into metadata.
mark_failed¶
- API：
public - 首次版本：
7.0.0
标记加载失败。
参数：
| 名称 | 说明 |
|---|---|
error_text |
错误文本。 |
p_metadata |
调用方元数据。 |
返回：当前状态。
结构：
p_metadata: Dictionary merged into metadata.
mark_released¶
- API：
public - 首次版本：
7.0.0
标记资源已释放。
参数：
| 名称 | 说明 |
|---|---|
p_metadata |
调用方元数据。 |
返回：当前状态。
结构：
p_metadata: Dictionary merged into metadata.
mark_stale¶
- API：
public - 首次版本：
7.0.0
标记资源状态已过期。
参数：
| 名称 | 说明 |
|---|---|
reason |
过期原因。 |
p_metadata |
调用方元数据。 |
返回：当前状态。
结构：
p_metadata: Dictionary merged into metadata.
is_success¶
- API：
public - 首次版本：
7.0.0
检查当前状态是否为成功终态。
返回：成功加载且资源引用有效时返回 true。
is_terminal¶
- API：
public - 首次版本：
7.0.0
检查当前状态是否为终态。
返回：loaded、failed 或 released 时返回 true。
to_dictionary¶
- API：
public - 首次版本：
7.0.0
导出状态字典。
返回：状态字典。
结构：
return: Dictionary，包含 resource_key、resource_path、status、progress、error、reference_mode、has_resource、resource_instance_id 和 metadata。
duplicate_state¶
- API：
public - 首次版本：
7.0.0
复制状态对象；当前资源引用会以相同引用模式传递。
返回：状态副本。
from_dictionary¶
- API：
public - 首次版本：
7.0.0
从字典恢复状态对象。资源引用不会从字典中恢复。
参数：
| 名称 | 说明 |
|---|---|
data |
to_dictionary() 兼容字典。 |
返回：状态对象。
结构：
data: Dictionary with resource_key, resource_path, status, progress, error, reference_mode and metadata.