将 Java 和 Kotlin 的输入 SDK 升级到 1.1 版

本指南介绍如何将您的游戏从 1.0.0-beta 版的 Java 和 Kotlin 输入 SDK 升级到 1.1.0-beta 版。有关 Unity 的特定说明，请参阅 Unity 升级指南。

发行说明

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

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

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

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

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

如果您想控制输入重新映射体验，或者如果为您的游戏禁用了重新映射功能，请执行以下步骤进行解决

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

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

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

您可以将输入 SDK 的版本升级到 1.1.0-beta，以利用 PC 上的 Google Play 游戏中的高级重新映射功能，方法是使用 InputContexts 为游戏的不同场景定义控件，添加回调以监听重新映射事件，定义一组用户无法重新映射的保留键，并停用每个 InputAction、InputGroup 或 InputMap 的重新映射功能。

升级到新 SDK 版本时，请考虑以下例外情况

不支持的配置

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

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

升级

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

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

触发场景控制更改.
接收按键映射事件的通知.
按操作、组、上下文或地图禁用重新映射。

升级依赖项

如果您使用 Gradle 导入输入 SDK，请升级到最新版本

// build.gradle
dependencies {
   ...
   implementation 'com.google.android.libraries.play.games:inputmapping:1.1.0-beta'
   ...
}

定义静态字段

对于版本 1.1.0-beta，最好将您的 InputAction、InputGroup、InputContext 和 InputMap 对象定义为 InputMappingProvider 类的静态字段，因为这些字段可从应用程序的其他部分访问

Kotlin

class InputSDKProvider : InputMappingProvider {
    override fun onProvideInputMap(): InputMap { return gameInputMap }

    companion object {
        const val INPUTMAP_VERSION = "1.0.0"

        private val moveUpInputAction = InputAction.create(...)
        private val movementInputGroup = InputGroup.create(...)
        val menuContext = InputContext.create(...)
        val gameInputMap = InputMap.create(...)
    }
}

Java

public class MyInputMappingProvider implements InputMappingProvider {
    private static final String INPUTMAP_VERSION = "1.0.0";

    private static final InputAction moveUpInputAction =
        InputAction.create(...);
    private static final InputGroup movementInputGroup = InputGroup.create(...);
    public static final InputContext menuContext = InputContext.create(...);
    public static final InputMap gameInputMap = InputMap.create(...);

    @Override
    public InputMap onProvideInputMap() {
        return gameInputMap;
    }
}

更新您的 InputActions

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

输入 SDK 1.0.0-beta 中的 InputAction

Kotlin

val jumpInputAction = InputAction.create(
    "Jump",
    InputEventIds.JUMP.id,
    InputControls.create(
        listOf(KeyEvent.KEYCODE_SPACE),
        emptyList()
    )
)

Java

InputAction moveUpInputAction = InputAction.create(
    "Move Up",
    InputEventIds.MOVE_UP.ordinal(),
    InputControls.create(
        Collections.singletonList(KeyEvent.KEYCODE_W),
        Collections.emptyList()
    )
);

输入 SDK 1.1.0-beta 中的 InputAction

Kotlin

companion object {
  private val moveUpInputAction = InputAction.create(
    "Move Up",
    InputActionsIds.DRIVE.ordinal.toLong(),
    InputControls.create(listOf(KeyEvent.KEYCODE_W), emptyList()),
    InputEnums.REMAP_OPTION_ENABLED) // This action is remappable
}

Java

private static final InputAction moveUpInputAction = InputAction.create(
    "Move Up",
    InputEventIds.MOVE_UP.ordinal(),
    InputControls.create(
            Collections.singletonList(KeyEvent.KEYCODE_W),
            Collections.emptyList()),
    InputEnums.REMAP_OPTION_ENABLED // this action is remappable
);

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

Kotlin

private val enterMenuInputAction = InputAction.create(
    "Enter menu",
    InputControls.create(listOf(KeyEvent.KEYCODE_ENTER), emptyList()),
    InputIdentifier.create(
    INPUTMAP_VERSION, InputActionsIds.ENTER_MENU.ordinal.toLong()),
    InputEnums.REMAP_OPTION_ENABLED
)

Java

private static final InputAction moveUpInputAction = InputAction.create(
    "Move Up",
    InputControls.create(
            Collections.singletonList(KeyEvent.KEYCODE_W),
            Collections.emptyList()),
    InputIdentifier.create(
            INPUTMAP_VERSION,
            InputEventIds.MOVE_UP.ordinal()),
    InputEnums.REMAP_OPTION_ENABLED // this action is remappable
);

有关版本控制按键绑定的更多信息，请参阅跟踪按键 ID。

更新您的 InputGroups

在输入 SDK 1.1.0-beta 中，您需要唯一标识每个 InputGroup。每个 InputAction 都属于一个 InputGroup（一组相关操作）。这将改进游戏过程中控件的导航和可发现性。与 InputAction 必须在单个 InputContext 中的所有操作中具有唯一标识符一样，InputGroup 也必须在现有组中具有唯一的 ID。

在本节的示例中，游戏有两个 InputContext 对象，分别代表主菜单和游戏玩法。这些上下文中的每个 InputGroup 的相应 ID 使用以下枚举进行跟踪

Kotlin

enum class 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
}

Java

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 一样，输入 SDK 1.0.0-beta 的 InputGroup.create() 方法已弃用。您必须使用版本标识符和布尔值更新游戏中的 InputGroup，以指示组中的 InputAction 对象是否可重新映射。使用已弃用的输入 SDK 1.0.0-beta create() 方法创建的组是可重新映射的，ID 为 0，版本 ID 为空字符串 ("")

输入 SDK 1.0.0-beta 中的 InputGroup

Kotlin

val movementInputGroup = InputGroup.create(
    "Basic Movement",
    listOf(
        moveUpInputAction,
        moveLeftInputAction,
        moveDownInputAction,
        moveRightInputAction,
        jumpInputAction,
        runInputAction)
)

Java

InputGroup movementInputGroup = InputGroup.create(
    "Basic movement",
    Arrays.asList(
        moveUpInputAction,
        moveLeftInputAction,
        moveDownInputAction,
        moveRightInputAction,
        jumpInputAction,
        runInputAction
    )
);

输入 SDK 1.1.0-beta 中的 InputGroup

Kotlin

companion object {
    private val movementInputGroup = InputGroup.create(
        "Basic movement",
        listOf(
            moveUpInputAction,
            moveLeftInputAction,
            moveDownInputAction,
            moveRightInputAction,
            jumpInputAction,
            runInputAction),
        InputGroupsIds.BASIC_MOVEMENT.ordinal.toLong(),
        // All the actions in this groups can't be remapped
        InputEnums.REMAP_OPTION_DISABLED
    )
}

Java

private static final InputGroup movementInputGroup = InputGroup.create(
    "Basic movement",
    Arrays.asList(
            moveUpInputAction,
            moveLeftInputAction,
            moveDownInputAction,
            moveRightInputAction,
            jumpInputAction,
            runInputAction
    ),
    InputGroupsIds.BASIC_MOVEMENT.ordinal(),
    // All the actions in this groups can't be remapped
    InputEnums.REMAP_OPTION_DISABLED
);

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

Kotlin

companion object {
    private val movementInputGroup  = InputGroup.create(
        "Basic movement",
        listOf(
            moveUpInputAction,
            moveLeftInputAction,
            moveDownInputAction,
            moveRightInputAction,
            jumpInputAction,
            runInputAction),
        InputIdentifier.create(
            INPUTMAP_VERSION, InputGroupsIds.BASIC_MOVEMENT.ordinal.toLong()),
        // All the actions in this groups can't be remapped
        InputEnums.REMAP_OPTION_DISABLED
    )
}

Java

private static final InputGroup movementInputGroup = InputGroup.create(
    "Basic movement",
    Arrays.asList(
            moveUpInputAction,
            moveLeftInputAction,
            moveDownInputAction,
            moveRightInputAction,
            jumpInputAction,
            runInputAction
    ),
    InputIdentifier.create(
            INPUTMAP_VERSION,
            InputGroupsIds.BASIC_MOVEMENT.ordinal()),
    // All the actions in this groups can't be remapped
    InputEnums.REMAP_OPTION_DISABLED
);

有关版本控制按键绑定的更多信息，请参阅跟踪按键 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

Kotlin

val gameInputMap = InputMap.create(
    listOf(movementInputGroup, mouseMovementInputGroup),
    MouseSettings.create(true, false)
)

Java

InputMap gameInputMap = InputMap.create(
    Arrays.asList(movementInputGroup, mouseMovementInputGroup),
    MouseSettings.create(true, false)
);

Input SDK 1.1.0-beta 中的 InputMap

Kotlin

companion object {

  const val INPUTMAP_VERSION = "1.0.0"
  const val INPUT_MAP_ID = 0

  val gameInputMap = InputMap.create(
    listOf(movementInputGroup, mouseMovementInputGroup),
    MouseSettings.create(true, false),
    InputIdentifier.create(INPUTMAP_VERSION, INPUT_MAP_ID.toLong()),
    InputEnums.REMAP_OPTION_ENABLED,
    // Use ESCAPE as reserved key
    listof(InputControls.create(listOf(KeyEvent.KEYCODE_ESCAPE), emptyList()))
  )
}

Java


public static final String INPUT_MAP_VERSION = "1.0.0-beta";
public static final long INPUT_MAP_ID = 0;

public static final InputMap gameInputMap = InputMap.create(
        Arrays.asList(movementInputGroup, mouseMovementInputGroup),
        MouseSettings.create(true, false),
        InputIdentifier.create(INPUTMAP_VERSION, INPUT_MAP_ID),
        InputEnums.REMAP_OPTION_ENABLED,
        // Use ESC key as reserved key
        Arrays.asList(
                InputControls.create(
                        Collections.singletonList(KeyEvent.KEYCODE_ESCAPE),
                        Collections.emptyList()
                )
        )
);

下一步

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

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