GFNodeStateGroup

API Reference / Standard / 类索引

• 路径：addons/gf/standard/state_machine/node/gf_node_state_group.gd
• 模块：Standard
• 继承：Node
• API：public
• 类别：运行时句柄 (runtime_handle)
• 首次版本：3.17.0

管理一组互斥激活的节点状态。 一个状态组内同一时间只有一个 GFNodeState 处于启用状态。

成员概览

类型	名称	签名
信号	state_added	signal state_added(state: GFNodeState)
信号	state_removed	signal state_removed(state: GFNodeState)
信号	current_state_changed	signal current_state_changed(old_state: GFNodeState, new_state: GFNodeState)
信号	transition_blocked	signal transition_blocked(from_state: GFNodeState, to_state_name: StringName, args: Dictionary, reason: String)
信号	requested_transition	signal requested_transition(group_name: StringName, state_name: StringName, args: Dictionary)
信号	state_event_handled	signal state_event_handled(event_id: StringName, handler_state: GFNodeState, payload: Variant)
属性	group_name	var group_name: StringName = &"":
属性	initial_state	var initial_state: StringName = &"":
属性	initial_args	var initial_args: Dictionary = {}
属性	reload_states_on_ready	var reload_states_on_ready: bool = true
属性	auto_start	var auto_start: bool = true:
属性	history_max_size	var history_max_size: int = 32
属性	max_stack_depth	var max_stack_depth: int = 8
属性	blackboard	var blackboard: Dictionary = {}
方法	get_group_name	func get_group_name() -> StringName:
方法	transition_to	func transition_to(next_state_name: StringName, args: Dictionary = {}) -> void:
方法	push_state	func push_state(next_state_name: StringName, args: Dictionary = {}) -> void:
方法	pop_state	func pop_state(args: Dictionary = {}) -> bool:
方法	add_state	func add_state(state: GFNodeState) -> void:
方法	remove_state	func remove_state(state: GFNodeState) -> bool:
方法	get_state	func get_state(query_state_name: StringName) -> GFNodeState:
方法	get_current_state	func get_current_state() -> GFNodeState:
方法	get_current_state_name	func get_current_state_name() -> StringName:
方法	get_state_history	func get_state_history() -> Array[StringName]:
方法	get_stack_depth	func get_stack_depth() -> int:
方法	get_blackboard	func get_blackboard() -> Dictionary:
方法	dispatch_state_event	func dispatch_state_event(event_id: StringName, payload: Variant = null) -> bool:
方法	is_in_state	func is_in_state(query_state_name: StringName) -> bool:
方法	restart	func restart(args: Dictionary = {}) -> void:
方法	start	func start(args: Dictionary = {}) -> void:
方法	stop	func stop() -> void:
方法	get_states	func get_states() -> Array[GFNodeState]:
方法	get_state_snapshot	func get_state_snapshot() -> Dictionary:
方法	clear_states	func clear_states(free_states: bool = false) -> void:
方法	reload_states_from_children	func reload_states_from_children() -> void:

信号

state_added

• API：public

signal state_added(state: GFNodeState)

状态加入组后发出。

参数：

名称	说明
state	新加入的状态节点。

state_removed

• API：public

signal state_removed(state: GFNodeState)

状态从组中移除后发出。

参数：

名称	说明
state	被移除的状态节点。

current_state_changed

• API：public

signal current_state_changed(old_state: GFNodeState, new_state: GFNodeState)

当前状态切换后发出。

参数：

名称	说明
old_state	切换前的状态；没有旧状态时为 null。
new_state	切换后的状态；状态组停止时可为 null。

transition_blocked

• API：public

signal transition_blocked(from_state: GFNodeState, to_state_name: StringName, args: Dictionary, reason: String)

状态切换被守卫阻止后发出。

参数：

名称	说明
from_state	发起切换时的当前状态；没有当前状态时为 null。
to_state_name	被阻止的目标状态名。
args	状态切换参数。
reason	阻止原因，通常为 "exit_guard" 或 "enter_guard"。

结构：

• args: 状态切换参数 Dictionary；键和值由调用方约定。

requested_transition

• API：public

signal requested_transition(group_name: StringName, state_name: StringName, args: Dictionary)

子状态请求跨组切换时发出。

参数：

名称	说明
group_name	目标状态组名。
state_name	目标状态名。
args	状态切换参数。

结构：

• args: 状态切换参数 Dictionary；键和值由调用方约定。

state_event_handled

• API：public

signal state_event_handled(event_id: StringName, handler_state: GFNodeState, payload: Variant)

当前状态或暂停栈状态处理状态事件后发出。

参数：

名称	说明
event_id	状态事件标识。
handler_state	实际处理事件的状态节点。
payload	状态事件载荷。

结构：

• payload: 状态事件载荷；具体结构由 event_id 和项目逻辑约定。

属性

group_name

• API：public

var group_name: StringName = &"":

状态组注册名。为空时使用节点名称。

initial_state

• API：public

var initial_state: StringName = &"":

初始状态名。

initial_args

• API：public

var initial_args: Dictionary = {}

初始状态参数。

结构：

• initial_args: 初始状态参数 Dictionary；键和值由初始状态的项目逻辑约定。

reload_states_on_ready

• API：public

var reload_states_on_ready: bool = true

ready 时是否自动从子节点加载状态。

auto_start

• API：public

var auto_start: bool = true:

初始化后是否自动进入 initial_state。关闭后可通过 start() 手动启动。

history_max_size

• API：public

var history_max_size: int = 32

每个状态组保留的历史状态名数量。

max_stack_depth

• API：public

var max_stack_depth: int = 8

push_state 可叠加的最大栈深度。

blackboard

• API：public

var blackboard: Dictionary = {}

状态组共享黑板。框架不解释其中字段。

结构：

• blackboard: 状态组共享黑板 Dictionary；键和值由项目状态逻辑约定。

方法

get_group_name

• API：public

func get_group_name() -> StringName:

获取状态组注册名。

返回：非空 group_name，或节点名称转换出的 StringName。

transition_to

• API：public

func transition_to(next_state_name: StringName, args: Dictionary = {}) -> void:

切换到指定状态。

参数：

名称	说明
next_state_name	要切换到的目标状态名称。
args	状态切换时传递的可选参数。

结构：

• args: 状态切换参数 Dictionary；键和值由调用方约定。

push_state

• API：public

func push_state(next_state_name: StringName, args: Dictionary = {}) -> void:

暂停当前状态并叠加进入一个子状态。

参数：

名称	说明
next_state_name	要切换到的目标状态名称。
args	状态切换时传递的可选参数。

结构：

• args: 状态切换参数 Dictionary；键和值由调用方约定。

pop_state

• API：public

func pop_state(args: Dictionary = {}) -> bool:

退出当前子状态并恢复上一层状态。

参数：

名称	说明
args	状态切换时传递的可选参数。

返回：成功恢复上一层状态时返回 true。

结构：

• args: 状态切换参数 Dictionary；键和值由调用方约定。

add_state

• API：public

func add_state(state: GFNodeState) -> void:

添加状态节点。

参数：

名称	说明
state	状态节点。

remove_state

• API：public

func remove_state(state: GFNodeState) -> bool:

移除状态节点。

参数：

名称	说明
state	状态节点。

返回：成功移除已注册状态时返回 true。

get_state

• API：public

func get_state(query_state_name: StringName) -> GFNodeState:

获取状态。

参数：

名称	说明
query_state_name	目标名称。

返回：注册名对应的状态节点；不存在时返回 null。

get_current_state

• API：public

func get_current_state() -> GFNodeState:

获取当前状态。

返回：当前激活状态；未启动或已停止时返回 null。

get_current_state_name

• API：public

func get_current_state_name() -> StringName:

获取当前状态名。

返回：当前激活状态名；未启动或已停止时返回空 StringName。

get_state_history

• API：public

func get_state_history() -> Array[StringName]:

获取状态切换历史。

返回：最近进入过的状态名列表。

结构：

• return: 状态历史 Array[StringName]，按进入顺序排列。

get_stack_depth

• API：public

func get_stack_depth() -> int:

获取当前暂停栈深度。

返回：当前暂停栈深度。

get_blackboard

• API：public

func get_blackboard() -> Dictionary:

获取状态组共享黑板。

返回：黑板字典。

结构：

• return: 状态组共享黑板 Dictionary；键和值由项目状态逻辑约定，调用方可直接修改。

dispatch_state_event

• API：public

func dispatch_state_event(event_id: StringName, payload: Variant = null) -> bool:

从当前状态开始向暂停栈上抛状态事件。

参数：

名称	说明
event_id	状态事件标识。
payload	状态事件载荷。

返回：有状态处理该事件时返回 true。

结构：

• payload: 状态事件载荷；具体结构由 event_id 和项目逻辑约定。

is_in_state

• API：public

func is_in_state(query_state_name: StringName) -> bool:

判断指定状态是否为当前状态或暂停栈中的状态。

参数：

名称	说明
query_state_name	目标名称。

返回：指定状态位于当前状态或暂停栈中时返回 true。

restart

• API：public

func restart(args: Dictionary = {}) -> void:

重启当前状态；若当前没有状态，则尝试进入初始状态。

参数：

名称	说明
args	状态切换时传递的可选参数。

结构：

• args: 状态切换参数 Dictionary；键和值由调用方约定。

start

• API：public

func start(args: Dictionary = {}) -> void:

进入初始状态。若已有当前状态则保持不变。

参数：

名称	说明
args	启动时传给初始状态的参数；为空时使用 initial_args。

结构：

• args: 启动参数 Dictionary；为空时使用 initial_args。

stop

• API：public

func stop() -> void:

停止当前激活状态，但保留已注册状态节点。

get_states

• API：public

func get_states() -> Array[GFNodeState]:

获取所有状态。

返回：已注册状态节点列表。

结构：

• return: 已注册 GFNodeState 节点数组。

get_state_snapshot

• API：public

func get_state_snapshot() -> Dictionary:

获取状态组调试快照。

返回：包含当前状态、暂停栈、历史、注册状态和黑板副本的字典。

结构：

• return: 调试快照 Dictionary，包含 group_name、current_state、stack、history、states 和 blackboard 字段。

clear_states

• API：public

func clear_states(free_states: bool = false) -> void:

清空状态。

参数：

名称	说明
free_states	为 true 时同时释放已移除的状态节点。

reload_states_from_children

• API：public

func reload_states_from_children() -> void:

从子节点重新加载状态。