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

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

发行说明

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

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

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

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

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

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

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

如果您想在仍然显示键绑定的只读版本的同时选择退出游戏的重新映射功能，请执行以下步骤

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

您可以将输入 SDK 的版本升级到 1.1.1-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.1-beta 与输入 SDK 1.0.0-beta 向后兼容。使用输入 SDK 的先前实现的游戏仍然支持基本重新映射，除非它们使用不受支持的配置。如果您的游戏使用的是早期版本的输入 SDK，请考虑阅读从 0.0.4 升级到 1.0.0-beta 的升级指南。

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

升级依赖项

如果您使用 Gradle 导入输入 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

输入 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.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
);

输入 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

在输入 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

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.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 继续升级到 1.1.1-beta，或者通过 在重新映射事件中获取通知 使用 InputRemappingListeners 更新游戏 UI。

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