游戏客户端架构 / 系统课时

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 合并;恢复默认就是删除覆盖项,不能用当前有效配置反过来覆盖系统默认。

先生成完整计划,再修改引擎映射

应用配置时按以下顺序进行,避免校验到一半已经清空旧绑定。

  1. 合并默认项与玩家覆盖,拒绝未知 binding id 和不支持的设备控制。
  2. 生成完整期望集合,核对动作名与所属模块,再暂停该模块采集并清理旧缓冲。
  3. 只替换受管动作的绑定,发布新配置版本;失败时恢复事先保存的旧集合。

下面是完整的项目配置规划器,保存为 godot_mapping_plan.js,使用 Node.js 执行 node godot_mapping_plan.js。它只操作普通数据,不会调用或模拟 Godot。控制名称是本例的项目协议,真正的适配器还须将其转换为 InputEventKey、手柄事件等引擎对象。

js
'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');

预期输出

text
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 信号,接收方分配逻辑帧和序号并写入项目队列;本片段不负责角色运动、重绑定保存或完整多设备状态合并。已有同名动作的绑定会保留。

gdscript
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;再检查菜单开启、失焦和恢复焦点时,旧跳跃意图不会延迟触发。记录配置计划与实际信号,分别证明配置合并正确和引擎接入正确。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

Godot的InputMap如何纳入架构

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通