Обновление Input SDK для Java и Kotlin до версии 1.1

В этом руководстве рассказывается, как обновить игру с версии 1.0.0-beta Input SDK для Java и Kotlin до версии 1.1.1-beta. Инструкции для Unity приведены в руководстве по обновлению Unity.

Примечания к выпуску

Google Play Games на компьютере поддерживают переназначение клавиш на основе привязок клавиш, заданных в игре с помощью Input SDK.

Чтобы воспользоваться этой функцией, откройте оверлей, выберите элементы управления и нажмите на действие, которое хотите переназначить.

Google Play Игры на компьютере сопоставляют переназначенные пользователем элементы управления с элементами управления, заданными в игре по умолчанию. В этом случае игре не нужно знать о переназначении клавиш. Если вам нужно знать, какие новые клавиши используются для игрового действия, например чтобы показывать их на экране, вы можете зарегистрировать обратный вызов, чтобы получать уведомления о событиях переназначения.

Google Play Games на компьютере сохраняют переназначенные элементы управления локально, поэтому они действуют во всех игровых сеансах. Поскольку эти данные хранятся локально, они не влияют на работу мобильного приложения и удаляются при удалении Google Play Games на компьютере. Настройки управления не сохраняются на нескольких ПК.

Чтобы включить переназначение клавиш в игре, обновлять Input SDK не нужно, но если будет обнаружена неподдерживаемая конфигурация, переназначение может быть отключено.

Если вы хотите управлять переназначением клавиш или если эта функция отключена для вашей игры, выполните следующие действия:

Если вы хотите отключить функцию переназначения клавиш в своей игре, но при этом показывать версию с привязками клавиш только для чтения, выполните следующие действия:

  • Перейдите на Input SDK 1.1.1-beta.
  • Обновите InputMap, чтобы задать для функции переназначения значение disabled.

Вы можете обновить 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 не могут иметь один и тот же уникальный идентификатор.

Перейти

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

Метод InputAction.create() из Input SDK 1.0.0-beta устарел. У отпечатка InputAction теперь есть идентификатор версии, и его можно пометить как переназначаемый или нет. InputAction, определенный с помощью метода Input SDK 1.0.0-beta create(), по умолчанию можно переназначать, но он не содержит информации о версии:

InputAction в Input SDK 1.0.0-beta

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

InputAction в Input SDK 1.1.1-beta

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

InputAction в Input SDK 1.1.1-beta (со строкой версии)

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

Подробнее об управлении версиями привязок клавиш см. в разделе Отслеживание идентификаторов ключей.

Как обновить InputGroups

В поле "Входной SDK" 1.1.1-beta нужно уникальным образом идентифицировать каждый InputGroup. Каждое значение InputAction относится к определенному значению InputGroup, которое представляет собой набор связанных действий. Это упрощает навигацию и поиск элементов управления во время игры. Как и в случае с элементом InputAction, который должен иметь уникальный идентификатор среди всех действий в одном элементе InputContext, элемент InputGroup должен иметь уникальный идентификатор среди существующих групп.

В примерах из этого раздела в игре есть два объекта InputContext, представляющих главное меню и игровой процесс. Для каждого InputGroup в этих контекстах отслеживаются подходящие идентификаторы, используя следующие перечисления:

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, метод InputGroup.create() из Input SDK 1.0.0-beta больше не поддерживается. Вам необходимо обновить InputGroup в игре, добавив идентификатор версии и логическое значение, указывающее, можно ли переназначать объекты InputAction в группах. Группы, созданные с помощью устаревшего метода Input SDK 1.0.0-beta create(), можно переназначать, они имеют идентификатор 0, а идентификатор версии – пустую строку (""):

InputGroup в Input SDK 1.0.0-beta

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

InputGroup в Input SDK 1.1.1-beta

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

InputGroup в Input SDK 1.1.1-beta (со строкой версии)

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

Подробнее об управлении версиями привязок клавиш см. в разделе Отслеживание идентификаторов ключей.

Как обновить InputMap

Метод InputMap.create() из Input SDK 1.0.0-beta устарел. Обновите InputMap, чтобы назначить идентификатор версии, полностью отказаться от функции переназначения или назначить список зарезервированных клавиш, которые пользователь не сможет переназначить. Каждая клавиша InputMap, определенная с помощью метода Input SDK 1.0.0-beta create(), по умолчанию может быть переназначена, идентифицируется с помощью идентификатора 0 и не имеет зарезервированных клавиш.

InputMap в Input SDK 1.0.0-beta

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

InputMap в Input SDK 1.1.1-beta

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

Что дальше

Чтобы продолжить переход на версию 1.1.1-beta, выполните следующие действия: Назначьте разные элементы управления для разных сцен, используя InputContexts, или обновите интерфейс игры, получая уведомления о событиях переназначения с помощью InputRemappingListeners.

При изменении сочетаний клавиш ознакомьтесь с рекомендациями по их настройке и учитывайте ограничения и особенности функции переназначения.