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, on_event: Callable, priority: int = 0, owner: Object = null) -> void: |
| 方法 | unregister |
func unregister(event_type: Script, on_event: Callable) -> void: |
| 方法 | register_assignable |
func register_assignable(base_event_type: Script, on_event: Callable, priority: int = 0, owner: Object = null) -> void: |
| 方法 | unregister_assignable |
func unregister_assignable(base_event_type: Script, on_event: Callable) -> void: |
| 方法 | send |
func send(event_instance: Object) -> void: |
| 方法 | register_simple |
func register_simple(event_id: StringName, on_event: Callable, owner: Object = null) -> void: |
| 方法 | unregister_simple |
func unregister_simple(event_id: StringName, on_event: Callable) -> 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_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
默认最大事件嵌套派发深度。
属性¶
max_dispatch_depth¶
- API：
public
最大事件嵌套派发深度。小于等于 0 时不限制。
trace_enabled¶
- API：
public
是否记录事件派发追踪。默认关闭，避免调试数据持有过多运行时引用。
max_trace_entries¶
- API：
public
最多保留的事件派发追踪条目数。
方法¶
register¶
- API：
public
func register(event_type: Script, on_event: Callable, priority: int = 0, owner: Object = null) -> void:
注册特定脚本类型的事件监听器。
参数：
| 名称 | 说明 |
|---|---|
event_type |
要监听的脚本类型。 |
on_event |
事件发送时执行的回调函数。 |
priority |
回调优先级，数值越大越先执行，默认为 0。 |
owner |
可选监听拥有者，用于批量注销。 |
unregister¶
- API：
public
注销特定脚本类型的事件监听器。
参数：
| 名称 | 说明 |
|---|---|
event_type |
要注销的脚本类型。 |
on_event |
要移除的回调函数。 |
register_assignable¶
- API：
public
func register_assignable(base_event_type: Script, on_event: Callable, priority: int = 0, owner: Object = null) -> void:
注册可赋值类型事件监听器。 监听 base_event_type 时，也会收到继承自该脚本类型的事件实例。
参数：
| 名称 | 说明 |
|---|---|
base_event_type |
要监听的基类脚本类型。 |
on_event |
事件发送时执行的回调函数。 |
priority |
回调优先级，数值越大越先执行，默认为 0。 |
owner |
可选监听拥有者，用于批量注销。 |
unregister_assignable¶
- API：
public
注销可赋值类型事件监听器。
参数：
| 名称 | 说明 |
|---|---|
base_event_type |
注册时使用的基类脚本类型。 |
on_event |
要移除的回调函数。 |
send¶
- API：
public
将事件实例发送给其脚本类型的所有注册监听器。
参数：
| 名称 | 说明 |
|---|---|
event_instance |
要分发的事件实例。 |
register_simple¶
- API：
public
注册轻量级 StringName 事件监听器。
参数：
| 名称 | 说明 |
|---|---|
event_id |
StringName 事件标识符。 |
on_event |
回调函数，签名为 func(payload: Variant)。 |
owner |
可选监听拥有者，用于批量注销。 |
unregister_simple¶
- API：
public
注销轻量级 StringName 事件监听器。
参数：
| 名称 | 说明 |
|---|---|
event_id |
StringName 事件标识符。 |
on_event |
要移除的回调函数。 |
send_simple¶
- API：
public
将 payload 发送给指定 StringName 事件的所有注册监听器。
参数：
| 名称 | 说明 |
|---|---|
event_id |
StringName 事件标识符。 |
payload |
传递给监听器的数据，可为任意类型。 |
结构：
payload: Variant payload passed unchanged to simple event listeners.
unregister_owner¶
- API：
public
注销指定拥有者注册过的所有事件监听器。
参数：
| 名称 | 说明 |
|---|---|
owner |
监听拥有者。 |
get_debug_stats¶
- API：
public
获取事件系统诊断统计。
返回：包含类型事件、可赋值事件和简单事件监听数量的字典。
结构：
return: Dictionary containing listener counts, pending operation counts, dispatch counters, depth limits, and trace counters.
get_dispatch_trace¶
- API：
public
获取最近事件派发追踪条目。
返回：从旧到新的追踪条目副本。
结构：
return: Array of Dictionary trace entries with event, listener, owner, and dispatch metadata.
clear_dispatch_trace¶
- API：
public
清空事件派发追踪。
clear¶
- API：
public
清空所有已注册的事件监听器（包括类型事件和简单事件）。