手柄适配

提示

目前仅 UE （Win64 & macOS）做了适配

概述

• 描述：对 TapSDK 和 XDSDK 中的界面做了手柄操作的适配
• 最低版本：TapSDK-3.28.0 和 XDSDK-6.16.0
• 适配模块：目前仅 TapSDK 的成就模块没有适配
• 适配平台：Win64, macOS

API

class TAPCOMMON_API TapUECommon 
{
    /**
     * 开发者告知 SDK 当前是否是手柄输入
     * 比如：摇杆移动的时候调用 TapControllerStartup；鼠标移动的时候调用 TapControllerShutdown
     * @param InControllerType 开发者认定的手柄类型，仅输入提示的图标有区别
     **/
    static bool TapControllerStartup(ETapControllerType InControllerType);
    static void TapControllerShutdown();

    /**
     * 更新手柄输入配置，拥有默认值
     * DeadZone： 取值 [0 ~ 1]，忽略输入的值
     * CursorMaxSpeed：模拟光标的移动速度
     * ScrollMaxSpeed：滚动内置网页和 ScrollBox 的速度
     **/
    static void TapControllerUpdateConfig(const TSharedPtr<FTapControllerConfig>& InConfig);

    /**
     * 当前 SDK 手柄输入是否正在运行，需要TapControllerStartup 并且 有 SDK 界面正在展示才判定运行
     **/
    static bool IsTapControllerRunning();

    /**
     * SDK 手柄输入运行状态改变 前后的回调（用于开启和屏蔽游戏的手柄输入）
     **/
    static FOnTapControllerRunningStateChanged PreTapControllerRunningStateChange;
    static FOnTapControllerRunningStateChanged PostTapControllerRunningStateChanged;
};

接入指南

• 假定 StartGameControllerInput 和 StopGameControllerInput 是游戏手柄输入的控制函数

//当需要开启手柄输入时
｛
    StartGameControllerInput();
    
    ETapControllerType ConType = <<ControllerTypeYouDetected>>;
    TapUECommon::TapControllerStartup(ConType);
｝

//当需要停止手柄输入时
｛
    TapUECommon::TapControllerShutdown();
    
    StopGameControllerInput();
｝

// TapUECommon::PreTapControllerRunningStateChange(bool bRunning) 回调时
{
    if (bRunning)
    {
        StopGameControllerInput();
    }
}

// TapUECommon::PostTapControllerRunningStateChanged(bool bRunning) 回调时
{
    if (!bRunning)
    {
        StartGameControllerInput();
    }
}

提示

• 注意先后顺序，SDK 界面层级高于游戏，所以 SDK 手柄输入的优先级也应该更高
• 部分引擎框架的内容 可能被 SDK 更改，StartGameControllerInput 时可能需要视情况恢复
• Demo 中模拟了一套游戏的手柄操作以及接入示例，详细代码可参考 IDemoControllerManager 及其相关代码

注意项

Startup/Shutdown 和 Running 的区别：

• Startup/Shutdown: 可以理解为开启或关闭手柄模式；SDK 不自己判断是为了和游戏保持同步，另外如果不需要手柄模式可以不调用Startup
• Running: Startup 并且 SDK 有界面展示 就是 Running，是 SDK 手柄输入是否实际启动了

SDK 对引擎框架的操作：

• Running 开始
  • FSlateApplication::RegisterInputPreProcessor
  • FSlateUser::SetUserNavigationConfig
  • FCoreStyle::SetFocusBrush
• Running 结束
  • FSlateApplication::UnregisterInputPreProcessor
• 运行过程多次设置
  • FSlateUser::SetCursorVisibility
  • FSlateApplication::SetKeyboardFocus
  • FSlateApplication::ClearKeyboardFocus

SDK 使用到的输入：

• 模拟光标和聚焦移动：EKeys::Gamepad_LeftX, EKeys::Gamepad_LeftY
• 内置网页和ScrollBox滚动（目前只有上下滚动）：EKeys::Gamepad_RightX, EKeys::Gamepad_RightY
• 模拟光标和按钮点击：EKeys::Virtual_Accept
• 快捷键关闭：EKeys::Virtual_Back

提示

• SDK 目前只针对引擎标准的 FKey 输入值进行适配。如果 SDK 和 游戏 的 输入Key 不一致，可以自行转换
• 比如：Windows 开启 RawInput 做手柄适配的话，可以在 URawInputSettings 配置输入转换时尽可能转换为标准输入
• 如果还不一致，注册 IInputProcessor 做转换。可以参考 SDK 中遗留的 FDPadAxisInputConverter
• 注意多个 IInputProcessor 有执行的先后顺序