输入 SDK 使用入门

本文档介绍了如何在支持 Google Play 游戏电脑版的游戏中设置和显示输入 SDK。这些任务包括将该 SDK 添加到游戏中并生成输入映射，该映射包含游戏操作到用户输入的分配关系。

准备工作

在将输入 SDK 添加到游戏中之前，您必须使用游戏引擎的输入系统实现对键盘和鼠标输入的支持。

输入 SDK 会向 Google Play 游戏电脑版提供与游戏所使用的控件相关的信息，以便向用户显示相关控件。此外，它还可以允许为用户进行键盘重新映射（可选）。

每个控件都是一个 InputAction（例如“J”代表“Jump”[跳跃]），并且您可以将 InputActions 整理为 InputGroups。InputGroup 可能代表游戏中的不同模式，例如“驾车”“步行”或“主菜单”。此外，您还可以使用 InputContexts 来指示在游戏的不同时刻哪些组要处于活跃状态。

您可以让系统自动为您处理键盘重新映射，但如果您更愿意提供自己的控件重新映射接口，则可以停用输入 SDK 重新映射。

下面的序列图展示了输入 SDK 的 API 的工作原理：

显示调用输入 SDK API 的游戏实现及其与 Android 设备的互动过程的序列图。

如果您的游戏实现了输入 SDK，您的控件便会显示在 Google Play 游戏电脑版叠加层中。

Google Play 游戏电脑版叠加层

Google Play 游戏电脑版叠加层（简称“叠加层”）用于显示您的游戏所定义的控件。用户可随时通过按 Shift 键 + Tab 键来访问该叠加层。

Google Play 游戏电脑版叠加层。

有关按键绑定设计的最佳实践

设计按键绑定时，请考虑遵循以下最佳实践：

  • 将 InputActions 整理为逻辑上相关的 InputGroups，以便改进游戏过程中的控件导航和易发现程度。
  • 每个 InputGroup 最多分配到一个 InputContext。如果 InputMap 粒度精细，便可以在叠加层中提供更好的控件导航体验。
  • 为游戏的每个不同场景类型分别创建一个 InputContext。通常，您可以针对所有“菜单类”场景使用一个 InputContext。对于游戏中的任何迷你游戏或单个场景的替代控件，请分别使用不同的 InputContexts。
  • 如果您将两项操作设计为使用同一 InputContext 下的同一按键，请利用“Interact / Fire”等标签字符串。
  • 如果将两个按键设计为绑定到同一 InputAction，则应使用两个不同的 InputActions 在游戏中执行相同的操作。您可以针对这两个 InputActions 使用相同的标签字符串，但其 ID 必须有所区别。
  • 如果将某个辅助键应用于一组按键，请考虑让一个 InputAction 使用该辅助键，而不是让多个 InputActions 组合使用该辅助键（例如：应使用 Shift 键和 W、A、S、D，而非 Shift 键 + W、Shift 键 + A、Shift 键 + S、Shift 键 + D）。
  • 当用户向文本字段写入内容时，系统应自动停用输入重新映射。请遵循与实现 Android 文本字段相关的最佳实践，以确保 Android 能够检测游戏中的文本字段，并防止经过重新映射的按键对这些字段产生干扰。如果您的应用必须使用非常规的文本字段，请使用 setInputContext() 和包含空 InputGroups 列表的 InputContext 来手动停用重新映射。
  • 如果您的应用支持重新映射，请考虑更新可能与用户保存的版本存在冲突的敏感操作的按键绑定。请尽可能避免更改现有控件的 ID。

重新映射功能

Google Play 游戏电脑版支持根据您的游戏使用输入 SDK 提供的按键绑定进行键盘控件重新映射。这是可选设置，可以完全停用。例如，您可能想要提供自己的键盘重新映射接口。如需为您的游戏停用重新映射，您只需指定为 InputMap 停用重新映射选项即可（如需了解详情，请参阅构建 InputMap）。

如需访问该功能，用户需要打开叠加层，然后点击要重新映射的操作。在每个重新映射事件发生后，Google Play 游戏电脑版都会将每个用户重新映射的控件映射到您的游戏预期会接收的默认控件，因此您的游戏并不需要了解玩家的重新映射。您可以选择添加重新映射事件的回调，以便更新用于在游戏中显示键盘控件的资源。

尝试重新映射按键

Google Play 游戏电脑版会将为每位用户重新映射的控件存储在本地，以便让这类控件在不同的游戏会话之间保持不变。只有在 PC 平台上这些信息才会存储在磁盘中，因此不会对移动体验产生任何影响。如果用户卸载或重新安装 Google Play 游戏电脑版，系统将删除控件数据。这些数据无法在多台 PC 设备之间保持不变。

如需在您的游戏中支持重新映射功能，请避免以下限制：

重新映射的相关限制

如果按键绑定符合以下任何情况，重新映射功能可能会在您的游戏中停用：

  • 多按键 InputActions 并非由辅助键 + 非辅助键组成。例如：Shift 键 + A 就符合条件，但 A + B、Ctrl 键 + Alt 键或 Shift 键 + A + Tab 键就不符合条件。
  • InputMap 包含的 InputActions、InputGroups 或 InputContexts 具有重复的唯一 ID。

重新映射的局限性

设计用于重新映射的按键绑定时，请考虑以下局限性：

  • 不支持重新映射到按键组合。例如，用户无法将 Shift 键 + A 重新映射到 Ctrl 键 + B，或将 A 重新映射到 Shift 键 + A。
  • 不支持重新映射使用鼠标按钮的 InputActions。例如，无法重新映射 Shift 键 + 右键点击。

通过 Google Play 游戏电脑版模拟器测试按键重新映射

您可以随时在 Google Play 游戏电脑版模拟器中启用重新映射功能，只需发出以下 adb 命令即可：

adb shell dumpsys input_mapping_service --set RemappingFlagValue true

叠加层将如下图所示发生变化：

启用了按键重新映射功能的叠加层。

添加 SDK

根据开发平台安装输入 SDK。

Java 和 Kotlin

通过将依赖项添加到模块级 build.gradle 文件，获取适用于 Java 或 Kotlin 的输入 SDK：

dependencies {
  implementation 'com.google.android.libraries.play.games:inputmapping:1.1.1-beta'
  ...
}

Unity

输入 SDK 是一种标准 Unity 软件包，且具有多个依赖项。

您需要安装该软件包以及所有依赖项。您可以通过多种方式安装该软件包。

安装 .unitypackage

下载输入 SDK unitypackage 文件及其所有依赖项。您可以按以下步骤安装 .unitypackage：依次选择 Assets > Import package > Custom Package，然后找到您下载的文件。

使用 UPM 进行安装

或者，您也可以使用 Unity Package Manager 安装该软件包，只需下载 .tgz 并安装其依赖项即可：

使用 OpenUPM 进行安装

您可以使用 OpenUPM 安装该软件包。

$ openupm add com.google.android.libraries.play.games.inputmapping

示例游戏

有关如何与输入 SDK 集成的示例，请参阅适用于 Kotlin 或 Java 游戏的 AGDK 隧道以及适用于 Unity 游戏的 Trivial Kart。

生成按键绑定