Esta página foi traduzida pela API Cloud Translation.

Fazer upgrade do SDK de entrada para Unity para a versão 1.1

Este guia explica como fazer upgrade do seu jogo do SDK de entrada de Unity 1.0 para 1.1. Clique aqui para acessar as instruções sobre Java e Kotlin.

Notas de lançamento

O Google Play Games no PC oferece suporte para o remapeamento de controles de teclado com base nas vinculações de tecla do jogo usando o SDK de entrada.

Os usuários acessam esse recurso abrindo a sobreposição, selecionando controles e clicando na ação que querem remapear.

O Google Play Games no PC mapeia todas as entradas remapeadas pelo usuário para a entrada padrão do jogo. Dessa forma, o jogo não precisa ter conhecimento do remapeamento do jogador. Se você tem necessidade de saber a nova entrada de uma ação no jogo, como exibir os controles do teclado no jogo, registre um callback para receber a notificação sobre remapeamento de eventos.

O Google Play Games no PC armazena localmente os controles remapeados do usuário para que permaneçam nas sessões de jogo. Como essas configurações são armazenadas localmente, elas não afetam a experiência em dispositivos móveis e são excluídas após a desinstalação do Google Play Games no PC. As configurações não são mantidas em vários PCs.

Não é necessário fazer upgrade do SDK de entrada para ativar o remapeamento de teclas no jogo, mas ele será desativado se uma configuração sem suporte for detectada.

Se você quiser controlar a experiência de remapeamento de entrada ou se o recurso de remapeamento for desativado no jogo, siga estas etapas:

Faça upgrade para o SDK de entrada 1.1.1-beta.
Atualize todas as vinculações de tecla para evitar as configurações sem suporte.
Atualize o InputMap para definir o recurso de remapeamento como ativado.

Se você quiser desativar o recurso para o jogo enquanto ainda exibe a versão somente leitura das vinculações de tecla, siga estas etapas:

Faça upgrade para o SDK de entrada 1.1.1-beta.
Atualize o InputMap para definir o recurso de remapeamento como desativado.

Você pode fazer upgrade da versão do SDK de entrada para 1.1.1-beta e aproveitar os recursos avançados de remapeamento no Google Play Games no PC usando InputContexts para definir controles para diferentes cenas do jogo, adicionar callbacks para detectar eventos de remapeamento, definir um conjunto de teclas reservadas que o usuário não pode remapear e desativar o recurso de remapeamento por InputAction, InputGroup ou InputMap.

Ao fazer upgrade, considere as seguintes exceções:

Configurações sem suporte

O remapeamento de entrada será desativado se as seguintes condições não forem atendidas:

Um InputAction que utiliza várias chaves precisa ser composto por uma tecla modificadora e uma não modificadora. Por exemplo, Shift + A é válido, mas A + B, Ctrl + Alt e Shift + A + Tab são inválidos.
Dois ou mais objetos InputAction ou InputGroup não podem compartilhar o mesmo ID exclusivo.

Apresentação do InputContext

Um InputContext permite que um jogo use a mesma tecla para diferentes ações no jogo sem conflitos. Dessa forma, se um jogo usar espaço para pular durante a jogabilidade e para confirmar uma seleção de menu, os jogadores poderão remapear individualmente o espaço para enter nos menus e espaço para seta para cima ao jogar.

O diagrama de sequência a seguir mostra como a API setInputContext() funciona no tempo de execução:

Diagrama mostrando o fluxo do SDK de entrada ao remapear teclas.

Upgrade

Os jogos que usam implementações anteriores do SDK de entrada ainda oferecem suporte ao remapeamento básico, a menos que usem uma configuração sem suporte. Se o jogo estiver usando uma versão mais antiga do SDK de entrada, leia o guia de upgrade da versão 0.0.4 para a 1.0.0-beta.

O upgrade para a versão 1.1.1-beta ativa novos recursos, incluindo:

Acionamento de mudanças de contexto.
Recebimento de notificações de eventos de mapeamento de teclas.
Desativação do remapeamento por ação, grupo, contexto ou mapa.

Instalação

O plug-in do Unity v1.1.1-beta está disponível para uso. Você precisa excluir as versões anteriores do SDK de entrada instaladas no jogo e fazer upgrade para a versão atual.

Para adicionar o SDK de entrada v1.1.1-beta ao seu jogo, consulte Como adicionar o SDK.

Definir campos estáticos

Para a versão 1.1.1-beta, é recomendável definir InputActions, InputGroups, InputContexts e InputMap como campos estáticos da classe InputMappingProvider. Esses campos podem ser acessados de outras partes do aplicativo:

#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

Atualizar InputActions

O método InputAction.create() do SDK de entrada 1.0.0-beta foi descontinuado. Uma InputAction tem um identificador de versão e pode ser marcada como remapeável ou não. Uma InputAction definida com o método 1.0.0-beta create() do SDK de entrada é remapeável por padrão e não tem informações de controle de versões:

InputAction no SDK de entrada 1.0.0-beta

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

InputAction no SDK de entrada 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 no SDK de entrada 1.1.1-beta (com string de versão)

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

Para mais informações sobre o controle de versões das vinculações de tecla, consulte Como rastrear códigos de tecla.

Atualizar InputGroups

No SDK de entrada 1.1.1-beta, você precisa identificar exclusivamente cada InputGroup. Cada InputAction pertence a um InputGroup, uma coleção de ações relacionadas. Isso melhora a navegação e a detecção dos controles durante a jogabilidade. Assim como uma InputAction precisa ter um identificador exclusivo entre todas as ações em um único InputContext, um InputGroup precisa ter um ID exclusivo nos grupos existentes.

Para os exemplos desta seção, um jogo tem dois objetos InputContext que representam o menu principal e a jogabilidade. Os IDs adequados são rastreados para cada InputGroup nesses contextos usando a seguinte enumeração:

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
}

Como InputAction, o método InputGroup.create() do SDK de entrada 1.0.0-beta foi descontinuado. Atualize o InputGroup no jogo com um identificador de versão e um booleano que indicam se os objetos InputAction nos grupos são remapeáveis. Os grupos criados com o método descontinuado 1.0.0-beta create() do SDK de entrada são remapeáveis, têm o ID 0 e o ID da versão é uma string vazia (""):

InputGroup no SDK de entrada 1.0.0-beta

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

InputGroup no SDK de entrada 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 no SDK de entrada 1.1.1-beta (com string de versão)

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

Para mais informações sobre o controle de versões das vinculações de tecla, consulte Como rastrear códigos de tecla.

Atualizar InputMap

O método InputMap.create() do SDK de entrada 1.0.0-beta foi descontinuado. Atualize o InputMap para atribuir um identificador de versão, desativar completamente o recurso de remapeamento ou atribuir uma lista de teclas reservadas do jogo que você não quer que sejam usadas pelo usuário. Cada InputMap definido com o método 1.0.0-beta create() do SDK de entrada é remapeável por padrão, é identificado com o ID 0 e não tem nenhuma tecla reservada.

InputMap no SDK de entrada 1.0.0-beta

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

InputMap no SDK de entrada 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()
);

A seguir

Continue o upgrade para a versão 1.1.1-beta atribuindo controles diferentes para cenas diferentes com InputContexts ou atualizando a interface do jogo recebendo notificações sobre o remapeamento de eventos com InputRemappingListeners.

Ao atualizar as vinculações de tecla, dê uma olhada nas Práticas recomendadas para projetar vinculações de tecla e considere as restrições e limitações do recurso de remapeamento.