将 Java 和 Kotlin 版 Input SDK 升级到 1.1 版

本指南介绍了如何将游戏从 1.0.0-beta 版 Java 和 Kotlin Input SDK 升级到 1.1.1-beta 版。如需了解 Unity 特定的说明，请参阅 Unity 升级指南。

版本说明

Google Play 游戏电脑版支持根据您的游戏使用 Input SDK 提供的键绑定重新映射键盘控制。

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

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

Google Play 游戏电脑版会在本地存储每个用户重新映射的控制项，以便这些控制项在游戏会话中保持不变。由于这些控制项是本地存储的，因此不会影响移动体验，并在卸载 Google Play 游戏电脑版时删除。控制设置不会在多台电脑设备之间持久保存。

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

如果您想控制输入重新映射体验，或者如果您的游戏重新映射功能被停用，请按照以下步骤解决

  • 升级到 Input SDK 1.1.1-beta。
  • 更新所有键绑定以避免不支持的配置。
  • 更新您的 InputMap 以将重新映射功能设置为已启用。

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

  • 升级到 Input SDK 1.1.1-beta。
  • 更新您的 InputMap 以将重新映射功能设置为已停用。

您可以将 Input SDK 升级到 1.1.1-beta，以便利用 Google Play 游戏电脑版中的高级重新映射功能，方法是使用 InputContexts 定义游戏不同场景的控制项，添加回调以监听重新映射事件，定义一组用户无法重新映射的保留键，以及停用每个 InputAction、InputGroup 或 InputMap 的重新映射功能。

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

不支持的配置

如果不满足以下条件，输入重新映射功能将被停用

  • 采用多个按键的 InputAction 必须由一个修饰键和一个非修饰键组成。例如，Shift + A是有效的，但A + B, Ctrl + Alt和Shift + A + Tab是无效的。

  • 两个或更多 InputAction 或 InputGroup 对象不能共享相同的唯一 ID。

升级

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

升级到 1.1.1-beta 版可启用新功能，包括

升级依赖项

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

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

定义静态字段

对于 1.1.1-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

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

Input 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()
    )
);

Input SDK 1.1.1-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
);

Input SDK 1.1.1-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

在 Input SDK 1.1.1-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 类似，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

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
    )
);

Input SDK 1.1.1-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
);

Input SDK 1.1.1-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

Input SDK 1.0.0-beta 的 InputMap.create() 方法已废弃。更新您的 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.1-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 获取重新映射事件通知来继续将您的游戏升级到 1.1.1-beta 版。

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