GFNodeState¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/state_machine/node/gf_node_state.gd - 模块：
Standard - 继承：
Node - API：
public - 类别：协议与扩展点 (
protocol) - 首次版本：
3.17.0
基于场景树的状态节点。 适合需要直接访问动画、碰撞、输入或子节点的状态逻辑。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 信号 | requested_transition |
signal requested_transition(group_name: StringName, state_name: StringName, args: Dictionary) |
| 属性 | state_name |
var state_name: StringName = &"" |
| 属性 | enter_conditions |
var enter_conditions: Array[Resource] = [] |
| 属性 | exit_conditions |
var exit_conditions: Array[Resource] = [] |
| 属性 | behaviors |
var behaviors: Array[Resource] = [] |
| 属性 | host |
var host: Node: |
| 方法 | get_machine |
func get_machine() -> Object: |
| 方法 | get_group |
func get_group() -> Object: |
| 方法 | get_host |
func get_host() -> Node: |
| 方法 | get_state_name |
func get_state_name() -> StringName: |
| 方法 | enter |
func enter(previous_state: StringName = &"", args: Dictionary = {}) -> void: |
| 方法 | exit |
func exit(next_state: StringName = &"", args: Dictionary = {}) -> void: |
| 方法 | pause |
func pause(next_state: StringName = &"", args: Dictionary = {}) -> void: |
| 方法 | resume |
func resume(previous_state: StringName = &"", args: Dictionary = {}) -> void: |
| 方法 | transition_to |
func transition_to(path: StringName, args: Dictionary = {}) -> void: |
| 方法 | initialize |
func initialize() -> void: |
| 方法 | can_enter |
func can_enter(previous_state: StringName = &"", args: Dictionary = {}) -> bool: |
| 方法 | can_exit |
func can_exit(next_state: StringName = &"", args: Dictionary = {}) -> bool: |
| 方法 | get_blackboard |
func get_blackboard() -> Dictionary: |
| 方法 | handle_state_event |
func handle_state_event(event_id: StringName, payload: Variant = null) -> bool: |
| 方法 | get_architecture_or_null |
func get_architecture_or_null() -> GFArchitecture: |
| 方法 | get_model |
func get_model(model_type: Script, require_ready: bool = false) -> Object: |
| 方法 | get_system |
func get_system(system_type: Script, require_ready: bool = false) -> Object: |
| 方法 | get_utility |
func get_utility(utility_type: Script, require_ready: bool = false) -> Object: |
| 方法 | get_local_model |
func get_local_model(model_type: Script, require_ready: bool = false) -> Object: |
| 方法 | get_local_system |
func get_local_system(system_type: Script, require_ready: bool = false) -> Object: |
| 方法 | get_local_utility |
func get_local_utility(utility_type: Script, require_ready: bool = false) -> Object: |
| 方法 | send_command |
func send_command(command: Object) -> Variant: |
| 方法 | send_query |
func send_query(query: Object) -> Variant: |
| 方法 | send_event |
func send_event(event_instance: Object) -> void: |
| 方法 | send_simple_event |
func send_simple_event(event_id: StringName, payload: Variant = null) -> void: |
| 方法 | register_event |
func register_event(event_type: Script, callback: Callable, priority: int = 0) -> void: |
| 方法 | unregister_event |
func unregister_event(event_type: Script, callback: Callable) -> void: |
| 方法 | register_assignable_event |
func register_assignable_event(base_event_type: Script, callback: Callable, priority: int = 0) -> void: |
| 方法 | unregister_assignable_event |
func unregister_assignable_event(base_event_type: Script, callback: Callable) -> void: |
| 方法 | register_simple_event |
func register_simple_event(event_id: StringName, callback: Callable) -> void: |
| 方法 | unregister_simple_event |
func unregister_simple_event(event_id: StringName, callback: Callable) -> void: |
| 方法 | unregister_owner_events |
func unregister_owner_events() -> void: |
| 方法 | _initialize |
func _initialize() -> void: |
| 方法 | _can_enter |
func _can_enter(_previous_state: StringName = &"", _args: Dictionary = {}) -> bool: |
| 方法 | _can_exit |
func _can_exit(_next_state: StringName = &"", _args: Dictionary = {}) -> bool: |
| 方法 | _enter |
func _enter(_previous_state: StringName = &"", _args: Dictionary = {}) -> void: |
| 方法 | _exit |
func _exit(_next_state: StringName = &"", _args: Dictionary = {}) -> void: |
| 方法 | _pause |
func _pause(_next_state: StringName = &"", _args: Dictionary = {}) -> void: |
| 方法 | _resume |
func _resume(_previous_state: StringName = &"", _args: Dictionary = {}) -> void: |
| 方法 | _handle_state_event |
func _handle_state_event(_event_id: StringName, _payload: Variant = null) -> bool: |
信号¶
requested_transition¶
- API：
public
状态请求切换时发出，由所属状态组或状态机处理。
参数：
| 名称 | 说明 |
|---|---|
group_name |
目标状态组名。 |
state_name |
目标状态名。 |
args |
状态切换参数。 |
结构：
args: 状态切换参数 Dictionary；键和值由调用方约定。
属性¶
state_name¶
- API：
public
状态注册名。为空时使用节点名称。
enter_conditions¶
- API：
public
进入状态前需要全部通过的条件资源。
结构：
enter_conditions: 元素为 GFNodeStateCondition 或兼容 evaluate() 入口的 Resource 列表。
exit_conditions¶
- API：
public
离开状态前需要全部通过的条件资源。
结构：
exit_conditions: 元素为 GFNodeStateCondition 或兼容 evaluate() 入口的 Resource 列表。
behaviors¶
- API：
public
进入、退出、暂停、恢复和事件处理时调用的可复用行为资源。
结构：
behaviors: 元素为 GFNodeStateBehavior 或兼容状态生命周期入口的 Resource 列表。
host¶
- API：
public
状态机宿主节点。通常是 GFNodeStateMachine 的父节点。
方法¶
get_machine¶
- API：
public
获取所属状态机。
返回：所属 GFNodeStateMachine；尚未挂入状态组时返回 null。
get_group¶
- API：
public
获取所属状态组。
返回：所属 GFNodeStateGroup；尚未挂入状态组时返回 null。
get_host¶
- API：
public
获取状态机宿主节点。若无状态机，则退回到状态组父节点或当前父节点。
返回：状态机宿主节点；不可用时返回当前父节点或 null。
get_state_name¶
- API：
public
获取实际注册名。
返回：非空 state_name，或节点名称转换出的 StringName。
enter¶
- API：
public
进入状态。
参数：
| 名称 | 说明 |
|---|---|
previous_state |
上一个状态名称。 |
args |
状态切换时传递的可选参数。 |
结构：
args: 状态切换参数 Dictionary；键和值由调用方约定。
exit¶
- API：
public
离开状态。
参数：
| 名称 | 说明 |
|---|---|
next_state |
下一个状态名称。 |
args |
状态切换时传递的可选参数。 |
结构：
args: 状态切换参数 Dictionary；键和值由调用方约定。
pause¶
- API：
public
进入栈式子状态时暂停当前状态。
参数：
| 名称 | 说明 |
|---|---|
next_state |
下一个状态名称。 |
args |
状态切换时传递的可选参数。 |
结构：
args: 状态切换参数 Dictionary；键和值由调用方约定。
resume¶
- API：
public
弹出栈式子状态后恢复当前状态。
参数：
| 名称 | 说明 |
|---|---|
previous_state |
上一个状态名称。 |
args |
状态切换时传递的可选参数。 |
结构：
args: 状态切换参数 Dictionary；键和值由调用方约定。
transition_to¶
- API：
public
请求切换状态。path 可为 "State" 或 "Group/State"。
参数：
| 名称 | 说明 |
|---|---|
path |
资源路径或状态路径。 |
args |
状态切换时传递的可选参数。 |
结构：
args: 状态切换参数 Dictionary；键和值由调用方约定。
initialize¶
- API：
public
状态初始化 Hook。状态加入状态组时调用一次。
can_enter¶
- API：
public
判断是否允许进入状态。
参数：
| 名称 | 说明 |
|---|---|
previous_state |
来源状态名。 |
args |
切换参数。 |
返回：允许进入返回 true。
结构：
args: 状态切换参数 Dictionary；键和值由调用方约定。
can_exit¶
- API：
public
判断是否允许离开状态。
参数：
| 名称 | 说明 |
|---|---|
next_state |
目标状态名。 |
args |
切换参数。 |
返回：允许离开返回 true。
结构：
args: 状态切换参数 Dictionary；键和值由调用方约定。
get_blackboard¶
- API：
public
获取状态组共享黑板。
返回：黑板字典；没有状态组时返回空字典。
结构：
return: 状态组共享黑板 Dictionary；键和值由项目状态逻辑约定。
handle_state_event¶
- API：
public
处理状态事件。返回 false 时事件会继续交给同组的暂停栈状态。
参数：
| 名称 | 说明 |
|---|---|
event_id |
状态事件标识。 |
payload |
状态事件载荷。 |
返回：已处理返回 true。
结构：
payload: 状态事件载荷；具体结构由 event_id 和项目逻辑约定。
get_architecture_or_null¶
- API：
public
获取当前状态可用的架构实例。
返回：架构实例；状态未挂入可解析上下文时返回 null。
get_model¶
- API：
public
通过当前状态上下文获取 Model。
参数：
| 名称 | 说明 |
|---|---|
model_type |
模型脚本类型。 |
require_ready |
为 true 时，仅返回已完成 ready 阶段的实例。 |
返回：模型实例；不可用时返回 null。
get_system¶
- API：
public
通过当前状态上下文获取 System。
参数：
| 名称 | 说明 |
|---|---|
system_type |
系统脚本类型。 |
require_ready |
为 true 时，仅返回已完成 ready 阶段的实例。 |
返回：系统实例；不可用时返回 null。
get_utility¶
- API：
public
通过当前状态上下文获取 Utility。
参数：
| 名称 | 说明 |
|---|---|
utility_type |
工具脚本类型。 |
require_ready |
为 true 时，仅返回已完成 ready 阶段的实例。 |
返回：工具实例；不可用时返回 null。
get_local_model¶
- API：
public
仅从当前状态所属架构获取 Model，不回退父级架构。
参数：
| 名称 | 说明 |
|---|---|
model_type |
模型脚本类型。 |
require_ready |
为 true 时，仅返回已完成 ready 阶段的实例。 |
返回：当前架构中的模型实例；不可用时返回 null。
get_local_system¶
- API：
public
仅从当前状态所属架构获取 System，不回退父级架构。
参数：
| 名称 | 说明 |
|---|---|
system_type |
系统脚本类型。 |
require_ready |
为 true 时，仅返回已完成 ready 阶段的实例。 |
返回：当前架构中的系统实例；不可用时返回 null。
get_local_utility¶
- API：
public
仅从当前状态所属架构获取 Utility，不回退父级架构。
参数：
| 名称 | 说明 |
|---|---|
utility_type |
工具脚本类型。 |
require_ready |
为 true 时，仅返回已完成 ready 阶段的实例。 |
返回：当前架构中的工具实例；不可用时返回 null。
send_command¶
- API：
public
向当前状态上下文发送命令。
参数：
| 名称 | 说明 |
|---|---|
command |
要发送的命令实例。 |
返回：命令执行结果；无可用架构时返回 null。
结构：
return: 命令返回值；具体结构由 GFCommand 实现决定。
send_query¶
- API：
public
向当前状态上下文发送查询。
参数：
| 名称 | 说明 |
|---|---|
query |
要发送的查询实例。 |
返回：查询结果；无可用架构时返回 null。
结构：
return: 查询返回值；具体结构由 GFQuery 实现决定。
send_event¶
- API：
public
发送类型事件。
参数：
| 名称 | 说明 |
|---|---|
event_instance |
要分发的事件实例。 |
send_simple_event¶
- API：
public
发送轻量级 StringName 事件。
参数：
| 名称 | 说明 |
|---|---|
event_id |
StringName 事件标识符。 |
payload |
可选的事件附加数据。 |
结构：
payload: 轻量事件载荷；具体结构由 event_id 和项目逻辑约定。
register_event¶
- API：
public
注册类型事件监听器，默认以当前状态作为 owner。
参数：
| 名称 | 说明 |
|---|---|
event_type |
要监听的脚本类型。 |
callback |
回调函数。 |
priority |
回调优先级，数值越大越先执行，默认为 0。 |
unregister_event¶
- API：
public
注销类型事件监听器。
参数：
| 名称 | 说明 |
|---|---|
event_type |
要注销的脚本类型。 |
callback |
要移除的回调函数。 |
register_assignable_event¶
- API：
public
func register_assignable_event(base_event_type: Script, callback: Callable, priority: int = 0) -> void:
注册可赋值类型事件监听器，默认以当前状态作为 owner。
参数：
| 名称 | 说明 |
|---|---|
base_event_type |
要监听的基类脚本类型。 |
callback |
回调函数。 |
priority |
回调优先级，数值越大越先执行，默认为 0。 |
unregister_assignable_event¶
- API：
public
注销可赋值类型事件监听器。
参数：
| 名称 | 说明 |
|---|---|
base_event_type |
注册时使用的基类脚本类型。 |
callback |
要移除的回调函数。 |
register_simple_event¶
- API：
public
注册轻量级 StringName 事件监听器，默认以当前状态作为 owner。
参数：
| 名称 | 说明 |
|---|---|
event_id |
StringName 事件标识符。 |
callback |
回调函数，签名为 func(payload: Variant)。 |
unregister_simple_event¶
- API：
public
注销轻量级 StringName 事件监听器。
参数：
| 名称 | 说明 |
|---|---|
event_id |
StringName 事件标识符。 |
callback |
要移除的回调函数。 |
unregister_owner_events¶
- API：
public
注销当前状态通过事件代理注册过的全部监听器。
_initialize¶
- API：
protected
状态初始化扩展点。
_can_enter¶
- API：
protected
状态进入守卫扩展点。
参数：
| 名称 | 说明 |
|---|---|
_previous_state |
来源状态名。 |
_args |
状态切换参数。 |
返回：允许进入返回 true。
结构：
_args: 状态切换参数 Dictionary；键和值由调用方约定。
_can_exit¶
- API：
protected
状态退出守卫扩展点。
参数：
| 名称 | 说明 |
|---|---|
_next_state |
目标状态名。 |
_args |
状态切换参数。 |
返回：允许退出返回 true。
结构：
_args: 状态切换参数 Dictionary；键和值由调用方约定。
_enter¶
- API：
protected
状态进入扩展点。
参数：
| 名称 | 说明 |
|---|---|
_previous_state |
来源状态名。 |
_args |
状态切换参数。 |
结构：
_args: 状态切换参数 Dictionary；键和值由调用方约定。
_exit¶
- API：
protected
状态退出扩展点。
参数：
| 名称 | 说明 |
|---|---|
_next_state |
目标状态名。 |
_args |
状态切换参数。 |
结构：
_args: 状态切换参数 Dictionary；键和值由调用方约定。
_pause¶
- API：
protected
状态被栈式子状态覆盖时的扩展点。
参数：
| 名称 | 说明 |
|---|---|
_next_state |
目标状态名。 |
_args |
状态切换参数。 |
结构：
_args: 状态切换参数 Dictionary；键和值由调用方约定。
_resume¶
- API：
protected
状态从栈式子状态恢复时的扩展点。
参数：
| 名称 | 说明 |
|---|---|
_previous_state |
来源状态名。 |
_args |
状态切换参数。 |
结构：
_args: 状态切换参数 Dictionary；键和值由调用方约定。
_handle_state_event¶
- API：
protected
状态事件处理扩展点。
参数：
| 名称 | 说明 |
|---|---|
_event_id |
状态事件标识。 |
_payload |
状态事件载荷。 |
返回：已处理返回 true。
结构：
_payload: 状态事件载荷；具体结构由 _event_id 和项目逻辑约定。