游戏客户端架构 / 系统课时
Godot的InputMap如何纳入架构
Godot的InputMap如何纳入架构
在 Godot 中配置一个跳跃动作很容易,难点是换键、菜单抢占和跨引擎迁移后,玩法仍然遵守同一份输入契约。本课把 InputMap 放在适配层,保留项目自己的动作与配置规则,再用可执行的配置规划器验证重绑定结果。
学习目标
- 区分 InputMap 的设备映射职责与项目的 Context、缓冲职责。
- 将项目绑定配置转换为受控的 Godot 动作,不破坏内置 UI 映射。
- 正确选择事件接入与状态轮询,并解释两者的边界。
InputMap 管映射,项目管语义
InputMap 把键盘、手柄等事件关联到引擎动作名;可以在项目设置中配置,也可以调用 add_action() 与 action_add_event()。本课约定引擎名 game_jump 对应项目语义 Jump,这个命名约定属于项目,不是 Godot 内置接口。官方 InputMap 文档
角色只接收 Jump 意图,不读取键位。菜单是否阻断跳跃、指令能缓冲多久、多个设备是否属于同一玩家,都由项目层决定。把这些规则藏进各个角色脚本,会让改键和换引擎重新侵入玩法代码。
还要明确配置所有权:适配器只更新自己管理的动作,保留 ui_accept 等其他动作。玩家覆盖项以稳定的 binding id 合并;恢复默认就是删除覆盖项,不能用当前有效配置反过来覆盖系统默认。
先生成完整计划,再修改引擎映射
应用配置时按以下顺序进行,避免校验到一半已经清空旧绑定。
- 合并默认项与玩家覆盖,拒绝未知 binding id 和不支持的设备控制。
- 生成完整期望集合,核对动作名与所属模块,再暂停该模块采集并清理旧缓冲。
- 只替换受管动作的绑定,发布新配置版本;失败时恢复事先保存的旧集合。
下面是完整的项目配置规划器,保存为 godot_mapping_plan.js,使用 Node.js 执行 node godot_mapping_plan.js。它只操作普通数据,不会调用或模拟 Godot。控制名称是本例的项目协议,真正的适配器还须将其转换为 InputEventKey、手柄事件等引擎对象。
'use strict';
const assert = require('node:assert/strict');
function buildPlan(defaults, overrides) {
const allowed = new Set(['KeyA', 'KeyJ', 'Space', 'GamepadSouth']);
const ids = new Set();
for (const binding of defaults) {
assert(!ids.has(binding.id), 'duplicate binding id');
assert(/^game_[a-z_]+$/.test(binding.action), 'unmanaged action');
ids.add(binding.id);
}
for (const id of Object.keys(overrides)) {
assert(ids.has(id), 'unknown override');
}
const grouped = new Map();
for (const binding of defaults) {
// 覆盖控制项,不能通过玩家配置改写动作归属。
const control = overrides[binding.id] ?? binding.control;
assert(allowed.has(control), 'unsupported control');
if (!grouped.has(binding.action)) grouped.set(binding.action, new Set());
grouped.get(binding.action).add(control);
}
// ASCII 标识符排序不依赖操作系统区域设置。
return [...grouped.keys()].sort().map(action => ({
action, controls: [...grouped.get(action)].sort()
}));
}
const defaults = [
{ id: 'jump.keyboard', action: 'game_jump', control: 'Space' },
{ id: 'jump.pad', action: 'game_jump', control: 'GamepadSouth' },
{ id: 'left.keyboard', action: 'game_move_left', control: 'KeyA' }
];
const before = JSON.stringify(defaults);
const plan = buildPlan(defaults, { 'jump.keyboard': 'KeyJ' });
assert.equal(JSON.stringify(defaults), before, 'defaults were mutated');
assert.deepEqual(plan[0].controls, ['GamepadSouth', 'KeyJ']);
for (const item of plan) {
console.log(`${item.action}: ${item.controls.join(',')}`);
}
assert.throws(() => buildPlan(defaults, { missing: 'KeyJ' }), /unknown override/);
console.log('default bindings unchanged; unknown override rejected');预期输出
game_jump: GamepadSouth,KeyJ
game_move_left: KeyA
default bindings unchanged; unknown override rejected计划只列出本模块动作,并未把引擎全部动作当作替换目标。真正重载时,应先调用 action_get_events() 保存旧事件;受管动作的 action_erase_events() 会删除其全部绑定,因此必须一次补回完整集合。运行时修改也不会自动替玩家保存偏好。
从真实 Godot 事件进入项目接口
以下为 Godot 4 节点片段示例:保存为 InputBridge.gd 并挂到场景中的一个 Node。启动前由装配层连接 action_intent 信号,接收方分配逻辑帧和序号并写入项目队列;本片段不负责角色运动、重绑定保存或完整多设备状态合并。已有同名动作的绑定会保留。
extends Node
signal action_intent(action: StringName, phase: StringName)
const ENGINE_ACTION: StringName = &"game_jump"
func _ready() -> void:
if not InputMap.has_action(ENGINE_ACTION):
InputMap.add_action(ENGINE_ACTION)
var key := InputEventKey.new()
key.physical_keycode = KEY_SPACE
InputMap.action_add_event(ENGINE_ACTION, key)
func _unhandled_input(event: InputEvent) -> void:
# 不接受键盘自动重复;精确匹配避免额外修饰键误触发。
if event.is_action_pressed(ENGINE_ACTION, false, true):
action_intent.emit(&"Jump", &"pressed")
elif event.is_action_released(ENGINE_ACTION, true):
action_intent.emit(&"Jump", &"released")人工验证方法是:启动该场景,观察信号接收日志,轻按并释放空格,再让一个会消费事件的 UI 获得焦点。预期行为是未被上游消费的匹配事件进入队列;信号本身不会让角色跳跃。此节点片段已在 Godot 4.7.2 无窗口环境加载并检查默认绑定与事件匹配,尚未执行真实窗口、UI 抢占和设备预览。官方 InputEvent 文档
不要只接收 InputEventAction:它是人工构造的虚拟动作事件,物理按键不会自动变成这种对象。触屏按钮需要注入动作时,可成对构造按下与释放事件,再用 Input.parse_input_event() 投递;不能假设 Input.action_press() 会调用节点的输入回调。官方 InputEventAction 文档
注入事件也要遵守引擎处理时机。无窗口 API 检查中,读取状态前先显式刷新事件缓冲;正常游戏由引擎在主循环中处理,不应在适配器里随意反复强制刷新。注入后立刻读取与下一帧采样的状态不能无条件视为等价。
避免轮询绕过界面和时序规则
连续移动可以在统一采样点读取 Input.get_axis(),但全局 Input 状态不受 UI 的事件消费影响。即使界面已经接收某个按键,角色轮询仍可能读到它;项目 Context 必须再次过滤状态,失焦或禁用玩法时输出零值并清理未消费边沿。官方 Input 文档
多个绑定同时按住时,释放其中一个来源不等于整个动作释放。若采用事件状态模型,要记录来源并聚合;若采用轮询聚合值,也要保留短按边沿队列,不能期待低频物理更新捕获所有快速点击。适配层集中执行一次采样,所有消费者读取同一帧快照。
练习:给跳跃增加第二个键盘绑定,验证玩家改键只替换指定 binding id;再检查菜单开启、失焦和恢复焦点时,旧跳跃意图不会延迟触发。记录配置计划与实际信号,分别证明配置合并正确和引擎接入正确。