Как обновить Input SDK для Unity до версии 1.1

В этом руководстве рассказывается, как обновить игру с Input SDK для Unity версии 1.0 до версии 1.1. Инструкции для Java и Kotlin

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

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

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

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

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

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

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

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

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

Вы можете обновить Input SDK до версии 1.1.1-beta, чтобы использовать расширенные функции переназначения клавиш в Google Play Games на ПК. Для этого используйте InputContexts, чтобы задавать элементы управления для разных сцен игры, добавлять обратные вызовы для прослушивания событий переназначения, определять набор зарезервированных клавиш, которые нельзя переназначить, и отключать функцию переназначения для InputAction, InputGroup или InputMap.

При переходе на новую версию учитывайте следующие исключения:

Неподдерживаемые конфигурации

Переназначение ввода будет отключено, если не соблюдаются следующие условия:

  • Сочетание клавиш InputAction должно состоять из клавиши-модификатора и обычной клавиши. Например, Shift + A – допустимое сочетание, а A + B, Ctrl + Alt и Shift + A + Tab – недопустимые.

  • Два или более объекта InputAction или InputGroup не могут иметь один и тот же уникальный идентификатор.

Представляем InputContext

InputContext позволяет использовать один и тот же ключ для разных действий в игре без конфликтов. Например, если в игре клавиша пробела используется для прыжка и подтверждения выбора в меню, игроки смогут переназначить ее на клавишу Ввод в меню и на клавишу Стрелка вверх во время игры.

На приведенной ниже диаграмме последовательности показано, как работает setInputContext() API во время выполнения:

Диаграмма, на которой показан поток Input SDK при переназначении клавиш.

Перейти

В играх, где используются предыдущие реализации Input SDK, по-прежнему поддерживается базовое переназначение клавиш, если только не используется неподдерживаемая конфигурация. Если в вашей игре используется более ранняя версия Input SDK, рекомендуем ознакомиться с руководством по обновлению с версии 0.0.4 до 1.0.0-beta.

Обновление до версии 1.1.1-beta открывает доступ к новым функциям, в том числе:

  • Изменение контекста.
  • Получение уведомлений о событиях сопоставления ключей
  • Отключение переназначения для действия, группы, контекста или карты.

Установка

Вы можете использовать плагин Unity версии 1.1.1-beta. Вам нужно удалить все предыдущие версии Input SDK, установленные в игре, и перейти на текущую версию.

Чтобы добавить Input SDK версии 1.1.1-beta в игру, следуйте инструкциям в разделе Добавление SDK.

Как задать статические поля

В версии 1.1.1-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

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

InputAction в Input SDK 1.0.0-beta

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

InputAction в Input SDK 1.1.1-beta

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

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

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

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

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

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

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

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

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

InputGroup в Input SDK 1.1.1-beta

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

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

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

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

Как обновить 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

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

InputMap в Input SDK 1.1.1-beta


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

Что дальше

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

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