GFAsyncWaitUtility

API Reference / Standard / 类索引

• 路径：addons/gf/standard/common/gf_async_wait_utility.gd
• 模块：Standard
• 继承：RefCounted
• API：public
• 类别：运行时服务 (runtime_service)
• 首次版本：7.0.0

公共 Signal 等待辅助。 提供带超时、取消 token、生命周期保护和 payload 捕获的 Signal、帧、延迟和条件等待入口。 它只负责等待状态，不创建业务任务，也不替代项目自己的流程编排。

成员概览

类型	名称	签名
常量	STATUS_COMPLETED	const STATUS_COMPLETED: StringName = &"completed"
常量	STATUS_CANCELLED	const STATUS_CANCELLED: StringName = &"cancelled"
常量	STATUS_TIMEOUT	const STATUS_TIMEOUT: StringName = &"timeout"
常量	STATUS_INVALID	const STATUS_INVALID: StringName = &"invalid"
方法	await_signal	static func await_signal(result_signal: Signal, options: Dictionary = {}) -> Dictionary:
方法	await_signal_payload	static func await_signal_payload(result_signal: Signal, options: Dictionary = {}) -> Dictionary:
方法	next_frame	static func next_frame(options: Dictionary = {}) -> Dictionary:
方法	physics_frame	static func physics_frame(options: Dictionary = {}) -> Dictionary:
方法	delay_seconds	static func delay_seconds(seconds: float, options: Dictionary = {}) -> Dictionary:
方法	wait_until	static func wait_until(predicate: Callable, options: Dictionary = {}) -> Dictionary:
方法	wait_while	static func wait_while(predicate: Callable, options: Dictionary = {}) -> Dictionary:
方法	wait_until_value_changed	static func wait_until_value_changed(getter: Callable, options: Dictionary = {}) -> Dictionary:

常量

STATUS_COMPLETED

• API：public
• 首次版本：7.0.0

const STATUS_COMPLETED: StringName = &"completed"

等待正常由目标 Signal 完成。

STATUS_CANCELLED

• API：public
• 首次版本：7.0.0

const STATUS_CANCELLED: StringName = &"cancelled"

等待被取消 token 结束。

STATUS_TIMEOUT

• API：public
• 首次版本：7.0.0

const STATUS_TIMEOUT: StringName = &"timeout"

等待因超时结束。

STATUS_INVALID

• API：public
• 首次版本：7.0.0

const STATUS_INVALID: StringName = &"invalid"

等待因目标或保护节点失效结束。

方法

await_signal

• API：public
• 首次版本：7.0.0

static func await_signal(result_signal: Signal, options: Dictionary = {}) -> Dictionary:

等待 Signal 发出，不捕获参数。

参数：

名称	说明
result_signal	要等待的 Signal。
options	等待选项。

返回：等待结果。

结构：

• options: Dictionary，可包含 timeout_seconds、cancel_token、guard_node、tree、time_utility、respect_time_scale、process_in_physics 和 timeout_warning。
• return: Dictionary，包含 status、completed、cancelled、timed_out、invalid、reason、metadata 和 args。

await_signal_payload

• API：public
• 首次版本：7.0.0

static func await_signal_payload(result_signal: Signal, options: Dictionary = {}) -> Dictionary:

等待 Signal 发出，并捕获最多 16 个参数。

参数：

名称	说明
result_signal	要等待的 Signal。
options	等待选项。

返回：等待结果。

结构：

• options: Dictionary，可包含 timeout_seconds、cancel_token、guard_node、tree、time_utility、respect_time_scale、process_in_physics 和 timeout_warning。
• return: Dictionary，包含 status、completed、cancelled、timed_out、invalid、reason、metadata 和 args。

next_frame

• API：public
• 首次版本：7.0.0

static func next_frame(options: Dictionary = {}) -> Dictionary:

等待下一帧 process_frame。

参数：

名称	说明
options	等待选项。

返回：等待结果。

结构：

• options: Dictionary，可包含 timeout_seconds、cancel_token、guard_node、tree、time_utility 和 respect_time_scale。
• return: Dictionary，包含 status、completed、cancelled、timed_out、invalid、reason、metadata 和 args。

physics_frame

• API：public
• 首次版本：7.0.0

static func physics_frame(options: Dictionary = {}) -> Dictionary:

等待下一帧 physics_frame。

参数：

名称	说明
options	等待选项。

返回：等待结果。

结构：

• options: Dictionary，可包含 timeout_seconds、cancel_token、guard_node、tree、time_utility 和 respect_time_scale。
• return: Dictionary，包含 status、completed、cancelled、timed_out、invalid、reason、metadata 和 args。

delay_seconds

• API：public
• 首次版本：7.0.0

static func delay_seconds(seconds: float, options: Dictionary = {}) -> Dictionary:

等待指定秒数。

参数：

名称	说明
seconds	等待秒数；小于等于 0 时立即完成。
options	等待选项。

返回：等待结果。

结构：

• options: Dictionary，可包含 timeout_seconds、cancel_token、guard_node、tree、time_utility、respect_time_scale 和 process_in_physics。
• return: Dictionary，包含 status、completed、cancelled、timed_out、invalid、reason、metadata 和 args。

wait_until

• API：public
• 首次版本：7.0.0

static func wait_until(predicate: Callable, options: Dictionary = {}) -> Dictionary:

等待 predicate 返回 true。

参数：

名称	说明
predicate	无参判断回调；返回值会收窄为 bool。
options	等待选项。

返回：等待结果。

结构：

• options: Dictionary，可包含 timeout_seconds、cancel_token、guard_node、tree、time_utility、respect_time_scale 和 process_in_physics。
• return: Dictionary，包含 status、completed、cancelled、timed_out、invalid、reason、metadata 和 args。

wait_while

• API：public
• 首次版本：7.0.0

static func wait_while(predicate: Callable, options: Dictionary = {}) -> Dictionary:

等待 predicate 返回 false。

参数：

名称	说明
predicate	无参判断回调；返回值会收窄为 bool。
options	等待选项。

返回：等待结果。

结构：

• options: Dictionary，可包含 timeout_seconds、cancel_token、guard_node、tree、time_utility、respect_time_scale 和 process_in_physics。
• return: Dictionary，包含 status、completed、cancelled、timed_out、invalid、reason、metadata 和 args。

wait_until_value_changed

• API：public
• 首次版本：7.0.0

static func wait_until_value_changed(getter: Callable, options: Dictionary = {}) -> Dictionary:

等待 getter 返回值发生变化。

参数：

名称	说明
getter	无参取值回调。
options	等待选项。

返回：等待结果；完成时包含 previous_value 和 value。

结构：

• options: Dictionary，可包含 timeout_seconds、cancel_token、guard_node、tree、time_utility、respect_time_scale 和 process_in_physics。
• return: Dictionary，包含 status、completed、cancelled、timed_out、invalid、reason、metadata、args、previous_value 和 value。