UE5.8 Common UI 喂饭级专题

UE5.8 Common UI 专题（五）：设备识别与按键图标

从 UCommonInputSubsystem、CommonInputSettings、CommonInputPlatformSettings、ControllerData、InputData、输入法抖动保护、手柄类型自动检测和图标查找讲到设置界面怎么显示键鼠/手柄/触摸提示。

UE5.8 Common UI CommonInput ControllerData Gamepad
开始阅读 返回 Unreal 索引

总览

游戏 UI 不能只显示“Press E”。玩家接手柄时要显示 A/B/X/Y 或 Cross/Circle；触摸设备要显示触摸按钮；键鼠又要显示 Space、Esc、Mouse Left。CommonInput 模块就是为这件事服务的。

UE5.8 Common UI 专题（五）：设备识别与按键图标 配图
CommonInput 负责判断当前玩家正在用什么设备，并把 FKey 转成对应平台的图标。

UCommonInputSubsystem 负责什么

UCommonInputSubsystem 是 ULocalPlayerSubsystem。它保存：

  • 当前有效输入类型：MouseAndKeyboard、Gamepad、Touch。
  • 默认输入类型。
  • 当前 GamepadName，例如 Generic、Xbox、PlayStation。
  • 输入类型过滤和锁。
  • 是否显示输入提示。
  • 是否正在经历输入法抖动。

输入设备切换来自 FCommonInputPreprocessor。源码里它会处理 KeyDown、Analog、MouseMove、MouseButton、Touch/Wheel，并根据 FKey 判断输入类型。

基础配置路径

Project Settings > Common Input：

  1. InputData 指向你的 BP_CommonInputData。
  2. bEnableEnhancedInputSupport 视项目启用。
  3. bEnableDefaultInputConfig 通常保持 true。
  4. bEnableAutomaticGamepadTypeDetection 通常保持 true。
  5. 配 ActionDomainTable 仅在你需要多个输入域时再做。

CommonUIInputData 里放 DefaultClickAction、DefaultBackAction、DefaultHoldData，Enhanced Input 模式下还可放 EnhancedInputClickAction/BackAction。

ControllerData 是按键图标表

创建蓝图类继承 CommonInputBaseControllerData，例如：

资产InputTypeGamepadName用途
BP_ControllerData_KeyboardMouseAndKeyboard空键盘鼠标图标
BP_ControllerData_XboxGamepadXboxXbox 手柄
BP_ControllerData_PSGamepadPlayStationPS 手柄
BP_ControllerData_TouchTouch空触摸图标

每个 ControllerData 里配置 InputBrushDataMap：FKey -> SlateBrush。也可以用 InputBrushKeySets，多个键共用一张图，例如鼠标滚轮上下显示同一个 Wheel 图标。

Platform Settings 决定支持什么设备

UCommonInputPlatformSettings 按平台配置：

  • DefaultInputType
  • bSupportsMouseAndKeyboard
  • bSupportsTouch
  • bSupportsGamepad
  • DefaultGamepadName
  • bCanChangeGamepadType
  • ControllerData

PC 通常支持键鼠和手柄，移动支持触摸和可选手柄，主机默认手柄但可能支持键鼠。别在 UI 代码里写一堆平台 if，尽量让 Platform Settings 决定。

输入法抖动保护

源码里 UCommonInputSettings 有 bEnableInputMethodThrashingProtection、InputMethodThrashingLimit、InputMethodThrashingWindowInSeconds、InputMethodThrashingCooldownInSeconds。它防止某些设备同时发鼠标和手柄事件时，UI 图标在键鼠/手柄之间疯狂闪。

如果玩家反馈提示图标一直跳，先看是不是触控板、Steam Input、手柄模拟鼠标在同时发事件。

使用案例：设置页显示当前键位

设置页里一个动作显示由三部分组成：

  1. Common UI binding 或 Enhanced Input mapping 得到当前 FKey。
  2. UCommonInputSubsystem 得到当前 InputType 和 GamepadName。
  3. UCommonActionWidget 或你自己的 glyph widget 调用 ControllerData 找 Brush。

如果找不到图标，先输出当前 GetCurrentInputType() 和 GetCurrentGamepadName()，再检查 PlatformSettings 里是否挂了对应 ControllerData。

常见坑

  • 只配了 Xbox 图标，PS 手柄自动检测后 GamepadName 变了，图标全空。
  • PC 平台没勾 bSupportsGamepad，接手柄也不显示手柄提示。
  • InputBrushDataMap 用了错误 FKey，例如 FaceButtonBottom 和具体平台图标对不上。
  • 开启 Steam Input 后输入类型一直抖动，没理解 thrashing protection。
  • Capture 视频时不想暴露设备，但没用 CommonInput.ShowKeys 控制提示显示。

源码依据

UCommonInputSubsystem 暴露 GetCurrentInputType、GetCurrentGamepadName、SetGamepadInputType、SetInputTypeFilter、AddOrRemoveInputTypeLock 和 HadAnyChangeOfInputMethodInTheLastThrashingWindow。CommonInputPreprocessor.cpp 根据 Key、Pointer、Touch 判断输入类型，并在自动手柄检测开启时通过 UInputDeviceSubsystem 查硬件设备。UCommonInputBaseControllerData 负责 FKey 到 SlateBrush，UCommonInputPlatformSettings 负责平台支持和 ControllerData 列表。

源码路径索引

  • CommonInput/Public/CommonInputSubsystem.h
  • CommonInput/Public/CommonInputSettings.h
  • CommonInput/Public/CommonInputBaseTypes.h
  • CommonInput/Private/CommonInputPreprocessor.cpp
  • CommonUI/Public/CommonActionWidget.h