将适用于 Unity 的输入 SDK 升级到 1.1 版

本指南介绍如何将你的游戏从 1.0 版升级到 1.1 版适用于 Unity 的输入 SDK。点击此处获取 Java 和 Kotlin 指令。

发行说明

Google Play 游戏在 PC 上支持根据你的游戏使用输入 SDK 提供的按键绑定重新映射键盘控制。

用户通过打开叠加层、选择 *控制*，然后点击他们要重新映射的操作来访问此功能。

Google Play 游戏在 PC 上将每个用户重新映射的输入映射到你的游戏的默认输入。这样，你的游戏就不必知道玩家的重新映射。如果你需要知道游戏内操作的新输入，例如在你的游戏中显示键盘控制，则可以选择注册回调以接收重新映射事件的通知。

Google Play 游戏在 PC 上将用户重新映射的控制存储在本地，以便在游戏会话之间持久保存。由于这些设置存储在本地，因此它们不会影响移动体验，并且在卸载 Google Play 游戏在 PC 上时会被删除。设置不会在多个 PC 设备之间持久保存。

你无需升级输入 SDK 即可在你的游戏中启用按键重新映射，但如果检测到不支持的配置，则会为你的游戏禁用重新映射。

如果你想要控制输入重新映射体验，或者你的游戏的重新映射功能被禁用，请按照以下步骤操作

升级到输入 SDK 1.1.0-beta。
更新任何按键绑定以避免不支持的配置。
更新你的 InputMap 以将重新映射功能设置为 *已启用*。

如果你想要选择退出游戏的重新映射功能，同时仍然显示按键绑定的只读版本，请按照以下步骤操作

升级到输入 SDK 1.1.0-beta。
更新你的 InputMap 以将重新映射功能设置为 *已禁用*。

你可以将你的输入 SDK 版本升级到 1.1.0-beta，以利用 Google Play 游戏在 PC 上的高级重新映射功能，通过使用 InputContexts 来定义游戏不同场景的控制，添加回调来侦听重新映射事件，定义一组用户无法重新映射的保留键，以及禁用每个 InputAction、InputGroup 或 InputMap 的重新映射功能。

升级时，请考虑以下异常情况

不支持的配置

如果未满足以下条件，则会禁用输入重新映射

使用多个键的 InputAction 必须由修饰键和非修饰键组成。例如，Shift + A有效，但A + B, Ctrl + Alt，以及Shift + A + Tab无效。
两个或多个 InputAction 或 InputGroup 对象不能共享相同的唯一 ID。

介绍 InputContext

一个 InputContext 允许游戏在你的游戏中使用相同的键执行不同的操作，而不会发生冲突。这样，如果游戏在游戏过程中使用空格键跳跃，并在确认菜单选择时使用空格键，玩家就可以分别重新映射空格键到回车键在菜单中，以及空格键到向上箭头在游戏过程中。

以下时序图显示了 setInputContext() API 在运行时的工作原理

Diagram showing the flow of the Input SDK when remapping keys.

升级

使用输入 SDK 的先前实现的游戏仍然支持基本重新映射，除非它们使用不支持的配置。如果你的游戏使用的是输入 SDK 的旧版本，请考虑阅读从 0.0.4 版升级到 1.0.0-beta 版的升级指南。

升级到 1.1.0-beta 版将启用新功能，包括

触发上下文更改。
接收按键映射事件的通知
禁用每个操作、组、上下文或映射的重新映射。

安装

适用于 Unity 的 1.1.0-beta 版插件现已提供使用。你需要删除你的游戏中安装的任何先前版本的输入 SDK 并升级到当前版本。

若要将 1.1.0-beta 版输入 SDK 添加到你的游戏中，请参阅添加 SDK。

定义静态字段

对于 1.1.0-beta 版，最佳做法是将你的 InputActions、InputGroups、InputContexts 和 InputMap 定义为 InputMappingProvider 类的静态字段，因为这些字段可以从你的应用程序的其他部分访问

#if PLAY_GAMES_PC
using Java.Lang;
using Java.Util;
using Google.Android.Libraries.Play.Games.Inputmapping;
using Google.Android.Libraries.Play.Games.Inputmapping.Datamodel;

public class InputSDKMappingProvider : InputMappingProviderCallbackHelper
{
    public static readonly string INPUT_MAP_VERSION = "1.0.0";

    private static readonly InputAction driveInputAction =
            InputAction.Create(...);
    private static readonly InputGroup roadInputGroup = InputGroup.Create(...);
    public static readonly InputContext roadControlsContext =
            InputContext.Create(...);
    public static readonly InputMap inputMap = InputMap.Create(...);

    public override InputMap OnProvideInputMap()
    {
        return inputMap;
    }
}
#endif

更新你的 InputActions

输入 SDK 1.0.0-beta 的 InputAction.create() 方法已弃用。一个 InputAction 具有版本标识符，可以标记为可重新映射或不可重新映射。使用输入 SDK 1.0.0-beta 的 create() 方法定义的 InputAction 默认情况下是可重新映射的，并且缺乏版本信息

输入 SDK 1.0.0-beta 中的 InputAction

var driveAction = PlayInputAction.Create(
    "Drive",
    (long)InputEventIds.DRIVE,
    PlayInputControls.Create(
        new[] { AndroidKeyCode.KEYCODE_SPACE },
        new List<PlayMouseAction>()
    )
);

输入 SDK 1.1.0-beta 中的 InputAction

private static readonly InputAction driveInputAction = InputAction.Create(
    "Drive",
    (long)InputEventIds.DRIVE,
    InputControls.Create(
        new[] { new Integer(AndroidKeyCode.KEYCODE_SPACE) }.ToJavaList(),
        new ArrayList<Integer>()),
    InputEnums.REMAP_OPTION_ENABLED
);

输入 SDK 1.1.0-beta 中的 InputAction（带有版本字符串）

private static readonly InputAction driveInputAction = InputAction.Create(
    "Drive",
    InputControls.Create(
        new[] { new Integer(AndroidKeyCode.KEYCODE_SPACE) }.ToJavaList(),
        new ArrayList<Integer>()),
    InputIdentifier.Create(
        INPUT_MAP_VERSION, (long)InputEventIds.DRIVE),
    InputEnums.REMAP_OPTION_ENABLED
);

有关为你的按键绑定添加版本的更多信息，请参阅跟踪按键 ID。

更新你的 InputGroups

在输入 SDK 1.1.0-beta 中，你需要唯一地标识每个 InputGroup。每个 InputAction 都属于一个 InputGroup -- 一组相关的操作。这将改善游戏过程中控制的导航和可发现性。正如一个 InputAction 在单个 InputContext 中的所有操作中必须具有 *唯一* 的标识符一样，一个 InputGroup 在现有的组中必须具有唯一的 ID。

对于本节中的示例，游戏有两个 InputContext 对象，分别代表主菜单和游戏过程。使用以下枚举为这些上下文中每个 InputGroup 跟踪适当的 ID

public enum InputGroupsIds
{
    // Main menu scene
    BASIC_NAVIGATION, // WASD, Enter, Backspace
    MENU_ACTIONS, // C: chat, Space: quick game, S: store
    // Gameplay scene
    BASIC_MOVEMENT, // WASD, space: jump, Shift: run
    MOUSE_ACTIONS, // Left click: shoot, Right click: aim
    EMOJIS, // Emojis with keys 1,2,3,4 and 5
    GAME_ACTIONS, // M: map, P: pause, R: reload
}

类似于 InputAction，Input SDK 1.0.0-beta 中的 InputGroup.create() 方法已弃用。您必须使用版本标识符和布尔值更新游戏中的 InputGroup，以指示组中的 InputAction 对象是否可重新映射。使用弃用的 Input SDK 1.0.0-beta create() 方法创建的组是可重新映射的，具有 ID 0，版本 ID 为空字符串 ("")

Input SDK 1.0.0-beta 中的 InputGroup

var gameInputGroup = PlayInputGroup.Create(
    "Road controls",
    new List<PlayInputAction>
    {
        driveAction,
        turboAction,
        openGarageAction,
        openPgsAction,
        openStoreAction
    }
);

Input SDK 1.1.0-beta 中的 InputGroup

private static readonly InputGroup roadInputGroup = InputGroup.Create(
    "Road controls",
    new[]
    {
        driveInputAction,
        turboInputAction,
        openGarageInputAction,
        openPgsInputAction,
        openStoreInputAction,
    }.ToJavaList(),
    (long)InputGroupsIds.ROAD_CONTROLS,
    // All input actions of this group will be remappable unless specified
    // the contrary by the individual input actions.
    InputEnums.REMAP_OPTION_ENABLED
);

Input SDK 1.1.0-beta 中的 InputGroup（带版本字符串）

private static readonly InputGroup roadInputGroup = InputGroup.Create(
    "Road controls",
    new[]
    {
        driveInputAction,
        turboInputAction,
        openGarageInputAction,
        openPgsInputAction,
        openStoreInputAction,
    }.ToJavaList(),
    InputIdentifier.Create(
        INPUT_MAP_VERSION, (long)InputGroupsIds.ROAD_CONTROLS),
    // All input actions of this group will be remappable unless specified
    // the contrary by the individual input actions.
    InputEnums.REMAP_OPTION_ENABLED
);

有关为你的按键绑定添加版本的更多信息，请参阅跟踪按键 ID。

更新您的 InputMap

InputMap.create() 方法的 Input SDK 1.0.0-beta 已弃用。更新您的 InputMap 以分配版本标识符，完全放弃重新映射功能或为您的游戏分配一个保留键列表，您不希望用户将其用于重新映射。使用 Input SDK 1.0.0-beta create() 方法定义的每个 InputMap 默认情况下都是可重新映射的，使用 ID 0 标识，并且没有任何保留键。

Input SDK 1.0.0-beta 中的 InputMap

var gameInputMap = PlayInputMap.Create(
    new List<PlayInputGroup>
    {
        gameInputGroup,
        menuInputGroup
    },
    PlayMouseSettings.Create(false, false)
);

Input SDK 1.1.0-beta 中的 InputMap


public static readonly string INPUT_MAP_VERSION = "1.0.0";
public static readonly long INPUT_MAP_ID = 0;

public static readonly InputMap inputMap = InputMap.Create(
    new[] { roadInputGroup, menuInputGroup }.ToJavaList(),
    MouseSettings.Create(false, false),
    InputIdentifier.Create(INPUT_MAP_VERSION, INPUT_MAP_ID),
    // Use ESC as reserved key
    InputEnums.REMAP_OPTION_ENABLED,
    new[]
    {
        InputControls.Create(new[]
        {
            new Integer(AndroidKeyCode.KEYCODE_ESCAPE)
        }.ToJavaList(),
        new ArrayList<Integer>())
    }.ToJavaList()
);

下一步

通过使用 InputContexts 为不同的场景分配不同的控制或通过使用 InputRemappingListeners 获取重新映射事件的通知更新游戏 UI，继续升级到 1.1.0-beta。

更新键绑定时，请查看设计键绑定的最佳实践，并考虑重新映射功能的限制和局限性。