GFTypeEventSystem

API Reference / Kernel / 类索引

• 路径：addons/gf/kernel/core/gf_type_event_system.gd
• 模块：Kernel
• 继承：Object
• API：public
• 类别：运行时服务 (runtime_service)
• 首次版本：3.17.0

基于类型和 StringName 的双轨事件系统。 轨道一（类型事件）：使用 Script 类型作为键，以对象实例为载体分发事件。 轨道二（简单事件）：使用 StringName 作为键，以 Variant 为 payload 分发事件。

成员概览

类型	名称	签名
常量	DEFAULT_MAX_DISPATCH_DEPTH	const DEFAULT_MAX_DISPATCH_DEPTH: int = 64
属性	max_dispatch_depth	var max_dispatch_depth: int = DEFAULT_MAX_DISPATCH_DEPTH:
属性	trace_enabled	var trace_enabled: bool = false
属性	max_trace_entries	var max_trace_entries: int = 64:
方法	register	func register(event_type: Script, listener: GFEventListener, priority: int = 0) -> void:
方法	register_owned	func register_owned(owner: Object, event_type: Script, listener: GFEventListener, priority: int = 0) -> void:
方法	unregister	func unregister(event_type: Script, listener: GFEventListener) -> void:
方法	unregister_owned	func unregister_owned(owner: Object, event_type: Script, listener: GFEventListener) -> void:
方法	register_assignable	func register_assignable(base_event_type: Script, listener: GFEventListener, priority: int = 0) -> void:
方法	register_assignable_owned	func register_assignable_owned( owner: Object, base_event_type: Script, listener: GFEventListener, priority: int = 0 ) -> void:
方法	unregister_assignable	func unregister_assignable(base_event_type: Script, listener: GFEventListener) -> void:
方法	unregister_assignable_owned	func unregister_assignable_owned(owner: Object, base_event_type: Script, listener: GFEventListener) -> void:
方法	send	func send(event_instance: Object) -> void:
方法	register_simple	func register_simple(event_id: StringName, listener: GFEventListener) -> void:
方法	register_simple_owned	func register_simple_owned(owner: Object, event_id: StringName, listener: GFEventListener) -> void:
方法	unregister_simple	func unregister_simple(event_id: StringName, listener: GFEventListener) -> void:
方法	unregister_simple_owned	func unregister_simple_owned(owner: Object, event_id: StringName, listener: GFEventListener) -> void:
方法	send_simple	func send_simple(event_id: StringName, payload: Variant = null) -> void:
方法	unregister_owner	func unregister_owner(owner: Object) -> void:
方法	get_debug_stats	func get_debug_stats() -> Dictionary:
方法	get_listener_diagnostics	func get_listener_diagnostics(options: Dictionary = {}) -> Dictionary:
方法	compact_released_owner_listeners	func compact_released_owner_listeners() -> int:
方法	get_dispatch_trace	func get_dispatch_trace() -> Array[Dictionary]:
方法	clear_dispatch_trace	func clear_dispatch_trace() -> void:
方法	clear	func clear() -> void:

常量

DEFAULT_MAX_DISPATCH_DEPTH

• API：public

const DEFAULT_MAX_DISPATCH_DEPTH: int = 64

默认最大事件嵌套派发深度。

属性

max_dispatch_depth

• API：public

var max_dispatch_depth: int = DEFAULT_MAX_DISPATCH_DEPTH:

最大事件嵌套派发深度。小于等于 0 时不限制。

trace_enabled

• API：public

var trace_enabled: bool = false

是否记录事件派发追踪。默认关闭，避免调试数据持有过多运行时引用。

max_trace_entries

• API：public

var max_trace_entries: int = 64:

最多保留的事件派发追踪条目数。

方法

register

• API：public
• 首次版本：8.0.0

func register(event_type: Script, listener: GFEventListener, priority: int = 0) -> void:

注册特定脚本类型的事件监听器。

参数：

名称	说明
event_type	要监听的脚本类型。
listener	事件监听器契约。
priority	回调优先级，数值越大越先执行，默认为 0。

register_owned

• API：public
• 首次版本：8.0.0

func register_owned(owner: Object, event_type: Script, listener: GFEventListener, priority: int = 0) -> void:

注册带 owner 的特定脚本类型事件监听器。

参数：

名称	说明
owner	监听 owner。
event_type	要监听的脚本类型。
listener	事件监听器契约。
priority	回调优先级，数值越大越先执行，默认为 0。

unregister

• API：public
• 首次版本：8.0.0

func unregister(event_type: Script, listener: GFEventListener) -> void:

注销特定脚本类型的事件监听器。

参数：

名称	说明
event_type	要注销的脚本类型。
listener	要移除的事件监听器契约。

unregister_owned

• API：public
• 首次版本：5.0.0

func unregister_owned(owner: Object, event_type: Script, listener: GFEventListener) -> void:

注销带拥有者的特定脚本类型事件监听器。

参数：

名称	说明
owner	注册监听时使用的拥有者。
event_type	要注销的脚本类型。
listener	要移除的事件监听器契约。

register_assignable

• API：public
• 首次版本：8.0.0

func register_assignable(base_event_type: Script, listener: GFEventListener, priority: int = 0) -> void:

注册可赋值类型事件监听器。 监听 base_event_type 时，也会收到继承自该脚本类型的事件实例。

参数：

名称	说明
base_event_type	要监听的基类脚本类型。
listener	事件监听器契约。
priority	回调优先级，数值越大越先执行，默认为 0。

register_assignable_owned

• API：public
• 首次版本：8.0.0

func register_assignable_owned( owner: Object, base_event_type: Script, listener: GFEventListener, priority: int = 0 ) -> void:

注册带 owner 的可赋值类型事件监听器。

参数：

名称	说明
owner	监听 owner。
base_event_type	要监听的基类脚本类型。
listener	事件监听器契约。
priority	回调优先级，数值越大越先执行，默认为 0。

unregister_assignable

• API：public
• 首次版本：8.0.0

func unregister_assignable(base_event_type: Script, listener: GFEventListener) -> void:

注销可赋值类型事件监听器。

参数：

名称	说明
base_event_type	注册时使用的基类脚本类型。
listener	要移除的事件监听器契约。

unregister_assignable_owned

• API：public
• 首次版本：5.0.0

func unregister_assignable_owned(owner: Object, base_event_type: Script, listener: GFEventListener) -> void:

注销带拥有者的可赋值类型事件监听器。

参数：

名称	说明
owner	注册监听时使用的拥有者。
base_event_type	注册时使用的基类脚本类型。
listener	要移除的事件监听器契约。

send

• API：public

func send(event_instance: Object) -> void:

将事件实例发送给其脚本类型的所有注册监听器。

参数：

名称	说明
event_instance	要分发的事件实例。

register_simple

• API：public
• 首次版本：8.0.0

func register_simple(event_id: StringName, listener: GFEventListener) -> void:

注册轻量级 StringName 事件监听器。

参数：

名称	说明
event_id	StringName 事件标识符。
listener	简单事件监听器契约。

register_simple_owned

• API：public
• 首次版本：8.0.0

func register_simple_owned(owner: Object, event_id: StringName, listener: GFEventListener) -> void:

注册带 owner 的轻量级 StringName 事件监听器。

参数：

名称	说明
owner	监听 owner。
event_id	StringName 事件标识符。
listener	简单事件监听器契约。

unregister_simple

• API：public
• 首次版本：8.0.0

func unregister_simple(event_id: StringName, listener: GFEventListener) -> void:

注销轻量级 StringName 事件监听器。

参数：

名称	说明
event_id	StringName 事件标识符。
listener	要移除的事件监听器契约。

unregister_simple_owned

• API：public
• 首次版本：5.0.0

func unregister_simple_owned(owner: Object, event_id: StringName, listener: GFEventListener) -> void:

注销带拥有者的轻量级 StringName 事件监听器。

参数：

名称	说明
owner	注册监听时使用的拥有者。
event_id	StringName 事件标识符。
listener	要移除的事件监听器契约。

send_simple

• API：public

func send_simple(event_id: StringName, payload: Variant = null) -> void:

将 payload 发送给指定 StringName 事件的所有注册监听器。

参数：

名称	说明
event_id	StringName 事件标识符。
payload	传递给监听器的数据，可为任意类型。

结构：

• payload: Variant payload passed unchanged to simple event listeners.

unregister_owner

• API：public

func unregister_owner(owner: Object) -> void:

注销指定拥有者注册过的所有事件监听器。

参数：

名称	说明
owner	监听拥有者。

get_debug_stats

• API：public

func get_debug_stats() -> Dictionary:

获取事件系统诊断统计。

返回：包含类型事件、可赋值事件和简单事件监听数量的字典。

结构：

• return: Dictionary containing listener counts, pending operation counts, dispatch counters, depth limits, and trace counters.

get_listener_diagnostics

• API：public
• 首次版本：7.0.0

func get_listener_diagnostics(options: Dictionary = {}) -> Dictionary:

获取事件监听器诊断明细。 默认只返回每条轨道的数量统计；传入 { "include_entries": true } 时会附带每个监听器的事件 key、owner 状态、优先级和 Callable 状态。

参数：

名称	说明
options	诊断选项。

返回：监听器诊断报告。

结构：

• options: Dictionary，可包含 include_entries。
• return: Dictionary containing listener counts, stale owner counts, track summaries, and optional entry rows.

compact_released_owner_listeners

• API：public
• 首次版本：7.0.0

func compact_released_owner_listeners() -> int:

清理 owner 已释放的监听器并返回清理数量。 派发期间调用时只会把清理动作加入 pending 队列，并在最外层派发结束后合并。

返回：本次立即移除或排队清理的监听器数量。

get_dispatch_trace

• API：public

func get_dispatch_trace() -> Array[Dictionary]:

获取最近事件派发追踪条目。

返回：从旧到新的追踪条目副本。

结构：

• return: Array of Dictionary trace entries with event, listener, owner, and dispatch metadata.

clear_dispatch_trace

• API：public

func clear_dispatch_trace() -> void:

清空事件派发追踪。

clear

• API：public

func clear() -> void:

清空所有已注册的事件监听器（包括类型事件和简单事件）。