GFInputMappingUtility¶
API Reference / Standard / 类索引
- 路径：
addons/gf/standard/input/runtime/gf_input_mapping_utility.gd - 模块：
Standard - 继承：
GFUtility - API：
public - 类别：运行时服务 (
runtime_service) - 首次版本：
3.17.0
资源化输入上下文与动作映射运行时。 负责把 Godot InputEvent 转换为项目定义的抽象动作状态，并支持上下文优先级、 运行时重绑定、动作值查询和一次性触发消费。
成员概览¶
| 类型 | 名称 | 签名 |
|---|---|---|
| 信号 | contexts_changed |
signal contexts_changed(contexts: Array[GFInputContext]) |
| 信号 | mappings_changed |
signal mappings_changed |
| 信号 | action_value_changed |
signal action_value_changed(action_id: StringName, value: Variant) |
| 信号 | action_started |
signal action_started(action_id: StringName, value: Variant) |
| 信号 | action_triggered |
signal action_triggered(action_id: StringName, value: Variant) |
| 信号 | action_completed |
signal action_completed(action_id: StringName, value: Variant) |
| 信号 | player_action_value_changed |
signal player_action_value_changed(player_index: int, action_id: StringName, value: Variant) |
| 信号 | player_action_started |
signal player_action_started(player_index: int, action_id: StringName, value: Variant) |
| 信号 | player_action_triggered |
signal player_action_triggered(player_index: int, action_id: StringName, value: Variant) |
| 信号 | player_action_completed |
signal player_action_completed(player_index: int, action_id: StringName, value: Variant) |
| 方法 | init |
func init() -> void: |
| 方法 | dispose |
func dispose() -> void: |
| 方法 | tick |
func tick(delta: float) -> void: |
| 方法 | set_remap_config |
func set_remap_config(config: GFInputRemapConfig) -> void: |
| 方法 | get_remap_config |
func get_remap_config(create_if_missing: bool = false) -> GFInputRemapConfig: |
| 方法 | enable_context |
func enable_context(context: GFInputContext, priority: int = 0) -> void: |
| 方法 | disable_context |
func disable_context(context: GFInputContext) -> void: |
| 方法 | set_enabled_contexts |
func set_enabled_contexts(contexts: Array[GFInputContext], priority: int = 0) -> void: |
| 方法 | clear_contexts |
func clear_contexts() -> void: |
| 方法 | is_context_enabled |
func is_context_enabled(context: GFInputContext) -> bool: |
| 方法 | get_enabled_contexts |
func get_enabled_contexts() -> Array[GFInputContext]: |
| 方法 | handle_input_event |
func handle_input_event(event: InputEvent) -> void: |
| 方法 | create_virtual_source |
func create_virtual_source( source_id: StringName = &"virtual", player_index: int = -1 ) -> GFVirtualInputSource: |
| 方法 | set_virtual_action_value |
func set_virtual_action_value( action_id: StringName, value: Variant, source_id: StringName = &"virtual", player_index: int = -1 ) -> bool: |
| 方法 | clear_virtual_action |
func clear_virtual_action( action_id: StringName, source_id: StringName = &"virtual", player_index: int = -1 ) -> bool: |
| 方法 | clear_virtual_source |
func clear_virtual_source(source_id: StringName = &"virtual") -> void: |
| 方法 | get_virtual_source_snapshot |
func get_virtual_source_snapshot(source_id: StringName = &"virtual") -> Dictionary: |
| 方法 | get_action_value |
func get_action_value(action_id: StringName) -> Variant: |
| 方法 | get_action_vector |
func get_action_vector(action_id: StringName) -> Vector2: |
| 方法 | get_action_vector3 |
func get_action_vector3(action_id: StringName) -> Vector3: |
| 方法 | is_action_active |
func is_action_active(action_id: StringName) -> bool: |
| 方法 | was_action_just_started |
func was_action_just_started(action_id: StringName) -> bool: |
| 方法 | was_action_just_completed |
func was_action_just_completed(action_id: StringName) -> bool: |
| 方法 | get_last_completed_duration |
func get_last_completed_duration(action_id: StringName) -> float: |
| 方法 | consume_action |
func consume_action(action_id: StringName) -> bool: |
| 方法 | get_action_value_for_player |
func get_action_value_for_player(player_index: int, action_id: StringName) -> Variant: |
| 方法 | get_action_vector_for_player |
func get_action_vector_for_player(player_index: int, action_id: StringName) -> Vector2: |
| 方法 | get_action_vector3_for_player |
func get_action_vector3_for_player(player_index: int, action_id: StringName) -> Vector3: |
| 方法 | is_action_active_for_player |
func is_action_active_for_player(player_index: int, action_id: StringName) -> bool: |
| 方法 | was_action_just_started_for_player |
func was_action_just_started_for_player(player_index: int, action_id: StringName) -> bool: |
| 方法 | was_action_just_completed_for_player |
func was_action_just_completed_for_player(player_index: int, action_id: StringName) -> bool: |
| 方法 | get_last_completed_duration_for_player |
func get_last_completed_duration_for_player(player_index: int, action_id: StringName) -> float: |
| 方法 | consume_action_for_player |
func consume_action_for_player(player_index: int, action_id: StringName) -> bool: |
| 方法 | set_binding_override |
func set_binding_override( context_id: StringName, action_id: StringName, binding_index: int, input_event: InputEvent ) -> void: |
| 方法 | unbind |
func unbind(context_id: StringName, action_id: StringName, binding_index: int) -> void: |
| 方法 | clear_binding_override |
func clear_binding_override(context_id: StringName, action_id: StringName, binding_index: int) -> void: |
| 方法 | get_remappable_items |
func get_remappable_items( context_filter: StringName = &"", display_category_filter: String = "" ) -> Array[Dictionary]: |
| 方法 | clear_input_state |
func clear_input_state() -> void: |
| 方法 | clear_player_input_state |
func clear_player_input_state(player_index: int) -> void: |
信号¶
contexts_changed¶
- API：
public
启用上下文变化后发出。
参数：
| 名称 | 说明 |
|---|---|
contexts |
当前启用上下文，已按运行时处理顺序排序。 |
结构：
contexts: Array[GFInputContext]，按有效优先级和激活时间戳排序。
mappings_changed¶
- API：
public
有效映射变化后发出。
action_value_changed¶
- API：
public
动作值变化时发出。
参数：
| 名称 | 说明 |
|---|---|
action_id |
动作标识。 |
value |
新动作值。 |
结构：
value: Variant，根据动作值类型使用 bool、float、Vector2 或 Vector3。
action_started¶
- API：
public
动作从非活跃变为活跃时发出。
参数：
| 名称 | 说明 |
|---|---|
action_id |
动作标识。 |
value |
激活时的动作值。 |
结构：
value: Variant，根据动作值类型使用 bool、float、Vector2 或 Vector3。
action_triggered¶
- API：
public
动作活跃且收到匹配输入事件时发出。
参数：
| 名称 | 说明 |
|---|---|
action_id |
动作标识。 |
value |
当前动作值。 |
结构：
value: Variant，根据动作值类型使用 bool、float、Vector2 或 Vector3。
action_completed¶
- API：
public
动作从活跃变为非活跃时发出。
参数：
| 名称 | 说明 |
|---|---|
action_id |
动作标识。 |
value |
完成时的动作值。 |
结构：
value: Variant，根据动作值类型使用 bool、float、Vector2 或 Vector3。
player_action_value_changed¶
- API：
public
玩家动作值变化时发出。
参数：
| 名称 | 说明 |
|---|---|
player_index |
玩家索引。 |
action_id |
动作标识。 |
value |
新动作值。 |
结构：
value: Variant，根据动作值类型使用 bool、float、Vector2 或 Vector3。
player_action_started¶
- API：
public
玩家动作从非活跃变为活跃时发出。
参数：
| 名称 | 说明 |
|---|---|
player_index |
玩家索引。 |
action_id |
动作标识。 |
value |
激活时的动作值。 |
结构：
value: Variant，根据动作值类型使用 bool、float、Vector2 或 Vector3。
player_action_triggered¶
- API：
public
玩家动作活跃且收到匹配输入事件时发出。
参数：
| 名称 | 说明 |
|---|---|
player_index |
玩家索引。 |
action_id |
动作标识。 |
value |
当前动作值。 |
结构：
value: Variant，根据动作值类型使用 bool、float、Vector2 或 Vector3。
player_action_completed¶
- API：
public
玩家动作从活跃变为非活跃时发出。
参数：
| 名称 | 说明 |
|---|---|
player_index |
玩家索引。 |
action_id |
动作标识。 |
value |
完成时的动作值。 |
结构：
value: Variant，根据动作值类型使用 bool、float、Vector2 或 Vector3。
方法¶
init¶
- API：
public
初始化输入映射运行时状态并挂载输入路由节点。
dispose¶
- API：
public
释放输入路由节点并清理全部运行时状态。
tick¶
- API：
public
推进运行时逻辑。
参数：
| 名称 | 说明 |
|---|---|
delta |
本帧时间增量（秒）。 |
set_remap_config¶
- API：
public
设置重映射配置。
参数：
| 名称 | 说明 |
|---|---|
config |
输入重映射配置；传 null 表示使用默认绑定。 |
get_remap_config¶
- API：
public
获取当前重映射配置。若不存在且 create_if_missing 为 true，会自动创建。
参数：
| 名称 | 说明 |
|---|---|
create_if_missing |
是否在缺失时创建。 |
返回：重映射配置。
enable_context¶
- API：
public
启用输入上下文。
参数：
| 名称 | 说明 |
|---|---|
context |
输入上下文资源。 |
priority |
优先级，数值越大越先处理。 |
disable_context¶
- API：
public
禁用输入上下文。
参数：
| 名称 | 说明 |
|---|---|
context |
输入上下文资源。 |
set_enabled_contexts¶
- API：
public
批量替换当前启用的上下文。
参数：
| 名称 | 说明 |
|---|---|
contexts |
输入上下文数组。 |
priority |
批量上下文默认优先级；数组越靠后，同优先级下越先处理。 |
结构：
contexts: Array[GFInputContext]，作为新的活跃 context 集启用。
clear_contexts¶
- API：
public
清空所有启用上下文。
is_context_enabled¶
- API：
public
检查上下文是否启用。
参数：
| 名称 | 说明 |
|---|---|
context |
输入上下文资源。 |
返回：是否启用。
get_enabled_contexts¶
- API：
public
获取已启用上下文，按实际处理顺序返回。
返回：上下文数组。
结构：
return: Array[GFInputContext]，按有效优先级和激活时间戳排序。
handle_input_event¶
- API：
public
手动处理输入事件。通常由内部路由节点自动调用，也可用于测试或自定义输入桥接。
参数：
| 名称 | 说明 |
|---|---|
event |
Godot 输入事件。 |
create_virtual_source¶
- API：
public
func create_virtual_source( source_id: StringName = &"virtual", player_index: int = -1 ) -> GFVirtualInputSource:
创建可编程虚拟输入源。
参数：
| 名称 | 说明 |
|---|---|
source_id |
虚拟输入源标识。 |
player_index |
玩家索引；小于 0 时只写入全局动作状态。 |
返回：虚拟输入源。
set_virtual_action_value¶
- API：
public
func set_virtual_action_value( action_id: StringName, value: Variant, source_id: StringName = &"virtual", player_index: int = -1 ) -> bool:
写入虚拟动作值。
参数：
| 名称 | 说明 |
|---|---|
action_id |
动作标识。 |
value |
动作值。 |
source_id |
虚拟输入源标识。 |
player_index |
玩家索引；小于 0 时只写入全局动作状态。 |
返回：写入成功返回 true。
结构：
value: Variant，要转换为动作运行时向量贡献的 bool、float、Vector2 或 Vector3 值。
clear_virtual_action¶
- API：
public
func clear_virtual_action( action_id: StringName, source_id: StringName = &"virtual", player_index: int = -1 ) -> bool:
清除虚拟动作值。
参数：
| 名称 | 说明 |
|---|---|
action_id |
动作标识。 |
source_id |
虚拟输入源标识。 |
player_index |
玩家索引；小于 0 时只清除全局动作状态。 |
返回：清除成功返回 true。
clear_virtual_source¶
- API：
public
清除指定虚拟输入源的所有动作贡献。
参数：
| 名称 | 说明 |
|---|---|
source_id |
虚拟输入源标识。 |
get_virtual_source_snapshot¶
- API：
public
获取虚拟输入源状态快照。
参数：
| 名称 | 说明 |
|---|---|
source_id |
虚拟输入源标识。 |
返回：快照字典。
结构：
return: Dictionary，包含 source_id 和 actions: Array[Dictionary]，action 条目包含 action_id 与 value。
get_action_value¶
- API：
public
获取动作当前值。
参数：
| 名称 | 说明 |
|---|---|
action_id |
动作标识。 |
返回：bool、float、Vector2 或 Vector3，取决于动作值类型。
结构：
return: Variant，根据动作值类型返回 bool、float、Vector2、Vector3 或 null。
get_action_vector¶
- API：
public
获取动作当前二维向量值。
参数：
| 名称 | 说明 |
|---|---|
action_id |
动作标识。 |
返回：二维向量值；三维轴会返回 x/y 分量。
get_action_vector3¶
- API：
public
获取动作当前三维向量值。
参数：
| 名称 | 说明 |
|---|---|
action_id |
动作标识。 |
返回：三维向量值；非三维动作的 z 分量为 0。
is_action_active¶
- API：
public
检查动作是否活跃。
参数：
| 名称 | 说明 |
|---|---|
action_id |
动作标识。 |
返回：是否活跃。
was_action_just_started¶
- API：
public
检查动作是否在当前帧刚刚开始。
参数：
| 名称 | 说明 |
|---|---|
action_id |
动作标识。 |
返回：是否刚开始。
was_action_just_completed¶
- API：
public
检查动作是否在当前帧刚刚结束。
参数：
| 名称 | 说明 |
|---|---|
action_id |
动作标识。 |
返回：是否刚结束。
get_last_completed_duration¶
- API：
public
获取动作最近一次结束前的持续活跃时间。
参数：
| 名称 | 说明 |
|---|---|
action_id |
动作标识。 |
返回：持续秒数。
consume_action¶
- API：
public
消费一次刚开始的动作。
参数：
| 名称 | 说明 |
|---|---|
action_id |
动作标识。 |
返回：成功消费返回 true。
get_action_value_for_player¶
- API：
public
获取指定玩家动作当前值。
参数：
| 名称 | 说明 |
|---|---|
player_index |
玩家索引。 |
action_id |
动作标识。 |
返回：bool、float、Vector2 或 Vector3，取决于动作值类型。
结构：
return: Variant，根据动作值类型返回 bool、float、Vector2、Vector3 或 null。
get_action_vector_for_player¶
- API：
public
获取指定玩家动作当前二维向量值。
参数：
| 名称 | 说明 |
|---|---|
player_index |
玩家索引。 |
action_id |
动作标识。 |
返回：二维向量值；三维轴会返回 x/y 分量。
get_action_vector3_for_player¶
- API：
public
获取指定玩家动作当前三维向量值。
参数：
| 名称 | 说明 |
|---|---|
player_index |
玩家索引。 |
action_id |
动作标识。 |
返回：三维向量值；非三维动作的 z 分量为 0。
is_action_active_for_player¶
- API：
public
检查指定玩家动作是否活跃。
参数：
| 名称 | 说明 |
|---|---|
player_index |
玩家索引。 |
action_id |
动作标识。 |
返回：是否活跃。
was_action_just_started_for_player¶
- API：
public
检查指定玩家动作是否在当前帧刚刚开始。
参数：
| 名称 | 说明 |
|---|---|
player_index |
玩家索引。 |
action_id |
动作标识。 |
返回：是否刚开始。
was_action_just_completed_for_player¶
- API：
public
检查指定玩家动作是否在当前帧刚刚结束。
参数：
| 名称 | 说明 |
|---|---|
player_index |
玩家索引。 |
action_id |
动作标识。 |
返回：是否刚结束。
get_last_completed_duration_for_player¶
- API：
public
获取指定玩家动作最近一次结束前的持续活跃时间。
参数：
| 名称 | 说明 |
|---|---|
player_index |
玩家索引。 |
action_id |
动作标识。 |
返回：持续秒数。
consume_action_for_player¶
- API：
public
消费指定玩家的一次刚开始动作。
参数：
| 名称 | 说明 |
|---|---|
player_index |
玩家索引。 |
action_id |
动作标识。 |
返回：成功消费返回 true。
set_binding_override¶
- API：
public
func set_binding_override( context_id: StringName, action_id: StringName, binding_index: int, input_event: InputEvent ) -> void:
设置某个绑定的运行时覆盖。
参数：
| 名称 | 说明 |
|---|---|
context_id |
上下文标识。 |
action_id |
动作标识。 |
binding_index |
绑定索引。 |
input_event |
新输入事件。 |
unbind¶
- API：
public
显式解绑某个绑定。
参数：
| 名称 | 说明 |
|---|---|
context_id |
上下文标识。 |
action_id |
动作标识。 |
binding_index |
绑定索引。 |
clear_binding_override¶
- API：
public
func clear_binding_override(context_id: StringName, action_id: StringName, binding_index: int) -> void:
清除某个绑定覆盖。
参数：
| 名称 | 说明 |
|---|---|
context_id |
上下文标识。 |
action_id |
动作标识。 |
binding_index |
绑定索引。 |
get_remappable_items¶
- API：
public
func get_remappable_items( context_filter: StringName = &"", display_category_filter: String = "" ) -> Array[Dictionary]:
获取可重绑条目。
参数：
| 名称 | 说明 |
|---|---|
context_filter |
可选上下文过滤。 |
display_category_filter |
可选显示分类过滤。 |
返回：条目字典数组。
结构：
return: Array[Dictionary]，包含 context、context_id、mapping、action、action_id、binding、binding_index、display_name、display_category 和 event 字段。
clear_input_state¶
- API：
public
清空所有动作运行时状态。
clear_player_input_state¶
- API：
public
清空指定玩家动作运行时状态。
参数：
| 名称 | 说明 |
|---|---|
player_index |
玩家索引。 |