Fazer upgrade do SDK de entrada para Java e Kotlin para a versão 1.1

Este guia explica como fazer upgrade do seu jogo do SDK de entrada 1.0.0-beta para Java e Kotlin para a versão 1.1.0-beta. Consulte o Guia de upgrade do Unity para instruções específicas.

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 de cada usuário para que eles sejam persistentes nas sessões de jogo. Como são armazenados dessa forma, isso não influencia a experiência móvel e os controles são excluídos após a desinstalação do Google Play Games no PC. As configurações de controle 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 estiver desativado para o jogo, siga estas etapas para resolver:

• Faça upgrade para o SDK de entrada 1.1.0-beta.
• Atualize todas as vinculações de tecla para evitar as configurações sem suporte.
• Atualize 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.0-beta.
• Atualize o InputMap para definir o recurso de remapeamento como desativado.

Você pode fazer upgrade da sua versão do SDK de entrada para 1.1.0-beta para 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 ouvir 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.

Considere as seguintes exceções ao fazer upgrade para a nova versão do SDK:

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 teclas 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 não são.

• Dois ou mais objetos InputAction ou InputGroup não podem compartilhar o mesmo ID exclusivo.

Upgrade

O SDK de entrada 1.1.0-beta é compatível com o SDK de entrada 1.0.0-beta. 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.0-beta ativa novos recursos, incluindo:

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

Fazer upgrade da dependência

Se você estiver usando o Gradle para importar o SDK de entrada, faça upgrade para a versão mais recente:

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

Definir campos estáticos

Para a versão 1.1.0-beta, é recomendável definir os objetos InputAction, InputGroup, InputContext e InputMap como campos estáticos da classe InputMappingProvider. Esses campos podem ser acessados em outras partes do aplicativo:

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(...)
    }
}

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

Atualizar InputActions

O método InputAction.create() do SDK de entrada 1.0.0-beta foi descontinuado. Agora, 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

val jumpInputAction = InputAction.create(
    "Jump",
    InputEventIds.JUMP.id,
    InputControls.create(
        listOf(KeyEvent.KEYCODE_SPACE),
        emptyList()
    )
)

InputAction moveUpInputAction = InputAction.create(
    "Move Up",
    InputEventIds.MOVE_UP.ordinal(),
    InputControls.create(
        Collections.singletonList(KeyEvent.KEYCODE_W),
        Collections.emptyList()
    )
);

InputAction no SDK de entrada 1.1.0-beta

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
}

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

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
)

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

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.0-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. Da mesma forma que 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:

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
}

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

val movementInputGroup = InputGroup.create(
    "Basic Movement",
    listOf(
        moveUpInputAction,
        moveLeftInputAction,
        moveDownInputAction,
        moveRightInputAction,
        jumpInputAction,
        runInputAction)
)

InputGroup movementInputGroup = InputGroup.create(
    "Basic movement",
    Arrays.asList(
        moveUpInputAction,
        moveLeftInputAction,
        moveDownInputAction,
        moveRightInputAction,
        jumpInputAction,
        runInputAction
    )
);

InputGroup no SDK de entrada 1.1.0-beta

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

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

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

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

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 para o 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

val gameInputMap = InputMap.create(
    listOf(movementInputGroup, mouseMovementInputGroup),
    MouseSettings.create(true, false)
)

InputMap gameInputMap = InputMap.create(
    Arrays.asList(movementInputGroup, mouseMovementInputGroup),
    MouseSettings.create(true, false)
);

InputMap no SDK de entrada 1.1.0-beta

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

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

A seguir

Continue o upgrade para a versão 1.1.0-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.