跳转至

GFTimerUtility

API Reference / Standard / 类索引

  • 路径：addons/gf/standard/utilities/time/gf_timer_utility.gd
  • 模块：Standard
  • 继承：GFUtility
  • API：public
  • 类别：运行时服务 (runtime_service)
  • 首次版本：3.17.0

纯代码驱动的全局定时器工具。 通过框架 tick() 驱动延时回调，不依赖场景树中的 Timer 节点， 因而可直接受到 GFTimeUtility 的时间缩放与暂停控制。适用于在 GFSystem、GFModel 或其他纯逻辑模块中调度一次性、重复或 owner 绑定任务。

成员概览

类型 名称 签名
方法 init func init() -> void:
方法 dispose func dispose() -> void:
方法 tick func tick(delta: float) -> void:
方法 execute_after func execute_after(delay: float, callback: Callable) -> int:
方法 execute_after_owned func execute_after_owned(owner: Object, delay: float, callback: Callable) -> int:
方法 execute_repeating func execute_repeating( interval: float, callback: Callable, repeat_count: int = -1, initial_delay: float = -1.0 ) -> int:
方法 execute_repeating_owned func execute_repeating_owned( owner: Object, interval: float, callback: Callable, repeat_count: int = -1, initial_delay: float = -1.0 ) -> int:
方法 cancel func cancel(handle: int) -> bool:
方法 cancel_owner func cancel_owner(owner: Object) -> int:
方法 get_debug_snapshot func get_debug_snapshot() -> Dictionary:

方法

init

  • API：public
func init() -> void:

初始化定时器队列。

dispose

  • API：public
func dispose() -> void:

清空定时器队列。

tick

  • API：public
func tick(delta: float) -> void:

推进运行时逻辑。

参数：

名称 说明
delta 本帧时间增量（秒）。

execute_after

  • API：public
func execute_after(delay: float, callback: Callable) -> int:

在指定延迟后执行一次回调函数。 基于框架 tick() 推进计时，因此会自动遵循 GFTimeUtility 的暂停与缩放结果。

参数：

名称 说明
delay 延迟时长，单位为秒。
callback 延迟结束后执行的无参回调函数。

返回：已排队定时器的句柄；无效回调或立即执行时返回 0。

execute_after_owned

  • API：public
func execute_after_owned(owner: Object, delay: float, callback: Callable) -> int:

在指定延迟后执行一次 owner 绑定回调。owner 释放后任务会自动丢弃。

参数：

名称 说明
owner 定时器拥有者。
delay 延迟时长，单位为秒。
callback 延迟结束后执行的无参回调函数。

返回：已排队定时器的句柄；无效输入或立即执行时返回 0。

execute_repeating

  • API：public
func execute_repeating( interval: float, callback: Callable, repeat_count: int = -1, initial_delay: float = -1.0 ) -> int:

按固定间隔重复执行回调。

参数：

名称 说明
interval 重复间隔，单位为秒。
callback 每次触发时执行的无参回调函数。
repeat_count 触发次数；小于 0 表示无限重复。
initial_delay 首次触发延迟；小于 0 时使用 interval。

返回：已排队定时器的句柄；无效输入时返回 0。

execute_repeating_owned

  • API：public
func execute_repeating_owned( owner: Object, interval: float, callback: Callable, repeat_count: int = -1, initial_delay: float = -1.0 ) -> int:

按固定间隔重复执行 owner 绑定回调。owner 释放后任务会自动丢弃。

参数：

名称 说明
owner 定时器拥有者。
interval 重复间隔，单位为秒。
callback 每次触发时执行的无参回调函数。
repeat_count 触发次数；小于 0 表示无限重复。
initial_delay 首次触发延迟；小于 0 时使用 interval。

返回：已排队定时器的句柄；无效输入时返回 0。

cancel

  • API：public
func cancel(handle: int) -> bool:

取消一个尚未触发的延时任务。

参数：

名称 说明
handle execute_after() 返回的定时器句柄。

返回：找到并取消任务时返回 true。

cancel_owner

  • API：public
func cancel_owner(owner: Object) -> int:

取消指定 owner 绑定的全部待执行任务。

参数：

名称 说明
owner 定时器拥有者。

返回：被取消的任务数量。

get_debug_snapshot

  • API：public
func get_debug_snapshot() -> Dictionary:

获取定时器工具诊断快照。

返回：诊断快照字典。

结构：

  • return: Dictionary with pending_count, pending_handles, owner_bound_count, executing_count, and next_timer_id.