Primeiros passos com o SDK de entrada

Este tópico descreve como configurar e exibir a sobreposição do SDK de entrada em jogos com suporte ao Google Play Games. As tarefas, incluindo a adição do SDK ao jogo e a geração de um mapa de entrada, contêm a ação do jogo para as atribuições de entrada do usuário. Para jogos com suporte a mudanças de vinculação de teclas, você também precisa rastrear e sincronizar as mudanças com o SDK.

Antes de começar

Antes de adicionar o SDK de entrada ao jogo, adicione suporte para teclado e mouse.

Adicionar o SDK

O SDK de entrada ainda não está disponível para download. Ele vai estar disponível como uma dependência do Maven para projetos Java e Kotlin, além de um unitypackage e o tgz para desenvolvedores do Unity.

Lembre-se de mostrar interesse em estar entre os primeiros a acessar o novo SDK.

Gerar mapeamento de entrada

O mapeamento de entrada representa as ações do jogo nas atribuições de entrada do usuário a serem exibidas na sobreposição do SDK de entrada. Para gerar o mapeamento de entrada, é necessário criar um InputMap e, em seguida, retorná-lo com um InputMappingProvider.

Veja um exemplo de um InputMappingProvider:

class MyInputMapProvider : InputMappingProvider() {
    override fun onProvideInputMap(): InputMap {
        TODO("Not yet implemented")
    }
}

public class MyInputMapProvider extends InputMappingProvider {
    @NonNull
    @Override
    public InputMap onProvideInputMap() {
        // TODO: return an InputMap
    }
}

private class MyInputMappingProvider : InputMappingProvider
{
    public InputMap OnProvideInputMap()
    {
        // TODO("Not yet implemented")
    }
}

As próximas seções descrevem como criar um InputMap para ser retornado do InputMappingProvider.

Definir uma ação de entrada

A classe InputAction é usada para mapear uma tecla ou uma combinação de teclas para uma ação do jogo.

Este exemplo mapeia a tecla de espaço para a ação de pular:

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

InputAction jumpInputAction = InputAction.create(
        "Jump",
        InputEventIds.JUMP.ordinal(),
        InputControls.create(
                Collections.singletonList(KeyEvent.KEYCODE_SPACE),
                Collections.emptyList()
        )
);

var jumpInputAction = new InputAction
{
    ActionLabel = "Jump",
    UniqueId = (int)InputEventIds.Jump,
    InputControls = new InputControls
    {
        AndroidKeycodes = new[]
        {
            AndroidKeyCode.KEYCODE_SPACE
        }
    }
};

As ações também podem representar entradas de mouse. Este exemplo define o botão direito do mouse para a ação de mover:

val cmbMove = InputAction.create(
    "Move",
    InputEventIds.CMB_MOVE.id,
    InputControls.create(
        emptyList(),
        listOf(InputControls.MOUSE_RIGHT_CLICK)
    )
)

InputAction cmbMove = InputAction.create(
        "Move",
        InputEventIds.CMB_MOVE.ordinal(),
        InputControls.create(
                Collections.emptyList(),
                Collections.singletonList(InputControls.MOUSE_RIGHT_CLICK)
        )
);

var cmbMove = new InputAction
{
    ActionLabel = "Move",
    UniqueId = (int)InputEventIds.CmbMove,
    InputControls = new InputControls
    {
        MouseActions = new[]
        {
            MouseAction.MouseRightClick
        }
    }
};

As combinações de teclas são especificadas transmitindo vários códigos de teclas para a InputAction. Neste exemplo, Espaço + Shift é mapeado para a ação de correr, que funciona mesmo quando a tecla de espaço é mapeada para pular.

val cmbDash = InputAction.create(
    "Dash",
    InputEventIds.CMB_DASH.id,
    InputControls.create(
        listOf(KeyEvent.KEYCODE_SPACE, KeyEvent.KEYCODE_SHIFT_LEFT),
        emptyList()
    )
)

InputAction cmbDash = InputAction.create(
        "Dash",
        InputEventIds.CMB_DASH.ordinal(),
        InputControls.create(
                Arrays.asList(KeyEvent.KEYCODE_SHIFT_LEFT, KeyEvent.KEYCODE_SPACE),
                Collections.emptyList()
        )
);

var cmbDash = new InputAction
{
    ActionLabel = "Dash",
    UniqueId = (int)InputEventIds.CmbDash,
    InputControls = new InputControls
    {
        AndroidKeycodes = new[]
        {
            AndroidKeyCode.KEYCODE_SPACE, AndroidKeyCode.KEYCODE_SHIFT_LEFT
        }
    }
};

O SDK de entrada permite combinar botões do mouse e do teclado para um único comando. Este exemplo indica que shift e clique com o botão direito do mouse pressionados adicionam um waypoint neste jogo:

val cmbWaypoint = InputAction.create(
    "Add Waypoint",
    InputEventIds.CMB_WAYPOINT.id,
    InputControls.create(
        listOf(KeyEvent.KEYCODE_SHIFT_LEFT),
        listOf(InputControls.MOUSE_RIGHT_CLICK)
    )
)

InputAction cmbWaypoint = InputAction.create(
        "Add Waypoint",
        InputEventIds.CMB_WAYPOINT.ordinal(),
        InputControls.create(
                Collections.singletonList(KeyEvent.KEYCODE_SHIFT_LEFT),
                Collections.singletonList(InputControls.MOUSE_RIGHT_CLICK)
        )
);

var cmbWaypoint = new InputAction
{
    ActionLabel = "Add Waypoint",
    UniqueId = (int)InputEventIds.CmbWaypoint,
    InputControls = new InputControls
    {
        AndroidKeycodes = new[]
        {
            AndroidKeyCode.KEYCODE_SHIFT_LEFT
        },
        MouseActions = new[]
        {
            MouseAction.MouseRightClick
        }
    }
};

Esta seção descreve os métodos chamados no exemplo de código:

Definir um grupo de entrada

Um InputGroup é um grupo de objetos InputAction semelhantes. Exemplo:

• Você pode especificar diferentes conjuntos de entradas para a navegação nos menus e a movimentação no jogo.
• Você pode especificar diferentes conjuntos de entradas, dependendo do modo de locomoção no jogo, como dirigir ou caminhar.
• Você pode especificar diferentes conjuntos de entradas com base no estado atual do jogo, como navegar em um mapa do mundo ou percorrer um nível individual.

Se você dividir as entradas em grupos temáticos, o jogador vai poder encontrar as teclas de atalho corretas para a situação atual com mais facilidade.

val movementInputGroup = InputGroup.create(
    "Basic Movement",
    listOf(jumpInputAction, leftInputAction, rightInputAction, useInputAction)
)

InputGroup movementInputGroup = InputGroup.create(
        "Basic Movement",
        Arrays.asList(jumpInputAction, leftInputAction, rightInputAction, useInputAction)
);

var movementInputGroup = new InputGroup
{
    GroupLabel = "Basic Movement",
    InputActions = new List<InputAction>
    {
        jumpInputAction,
        leftInputAction,
        rightInputAction,
        useInputAction
    }
}

Esta seção descreve as chamadas de método usadas no exemplo de código:

Criar um mapa de entrada

Um InputMap é uma coleção de todos os objetos InputGroup disponíveis em um jogo e, portanto, todos os objetos InputAction que um jogador pode esperar realizar.

No exemplo abaixo, objetos MovementInputGroup são agrupados com objetos MouseSettings. Os objetos MouseSettings indicam que a sensibilidade do mouse pode ser ajustada e que o mouse é invertido no eixo y:

return InputMap.create(
    listOf(movementInputGroup, specialInputGroup),
    MouseSettings.create(true, true)
)

return InputMap.create(
        Arrays.asList(movementInputGroup, specialInputGroup),
        MouseSettings.create(true, true)
);

return new InputMap
{
    InputGroups = new List<InputGroup> {movementInputGroup, specialInputGroup},
    MouseSettings = new MouseSettings
    {
        AllowMouseSensitivityAdjustment = true,
        InvertMouseMovement = true
    }
}

Enviar um mapa de entrada

Depois que um InputMapProvider for gravado para um jogo que retorna um InputMap válido, ele precisa ser registrado com o SDK de entrada. Se as entradas de um jogo nunca mudarem, esse registro precisa ser feito apenas uma vez durante a vida útil do jogo, já que o InputMapProvider não é afetado pelos eventos de ciclo de vida do Android.

private val myInputMapProvider by lazy {
    MyInputMapProvider()
}

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    val inputMappingClient = Input.getInputMappingClient(this)
    inputMappingClient.registerInputMappingProvider(myInputMapProvider)
}

private final MyInputMapProvider myInputMapProvider = new MyInputMapProvider();

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    InputMappingClient inputMappingClient = Input.getInputMappingClient(this);
    inputMappingClient.registerInputMappingProvider(myInputMapProvider);
}

public void Start() {
    InputMappingClient inputMappingClient = Input.GetInputMappingClient();
    inputMappingClient.registerInputMappingProvider(myInputMapProvider);
}

Cancele o registro do provedor de mapeamento de entrada quando o jogo for encerrado, mesmo que o SDK seja inteligente o suficiente para evitar o vazamento de recursos se você não fizer isso.

override fun onDestroy() {
    val inputMappingClient = Input.getInputMappingClient(this)
    inputMappingClient.unregisterInputMappingProvider(myInputMapProvider)

    super.onDestroy()
}

@Override
protected void onDestroy() {
    InputMappingClient inputMappingClient = Input.getInputMappingClient(this);
    inputMappingClient.unregisterInputMappingProvider(myInputMapProvider);

    super.onDestroy();
}

public void OnDestroy() {
    InputMappingClient inputMappingClient = Input.GetInputMappingClient();
    inputMappingClient.unregisterInputMappingProvider(myInputMapProvider);
}

Rastrear IDs de chave

É preciso rastrear IDs exclusivos para cada InputAction definida. A enumeração abaixo rastreia os IDs exclusivos de todos os exemplos deste tópico. Como os IDs são usados para rastrear as principais mudanças, não use um hash do nome da ação localizado.

enum class InputEventIds(val id: Int) {
    JUMP(0),
    LEFT(1),
    RIGHT(2),
    USE(3),
    SPECIAL_JUMP(4),
    SPECIAL_DUCK(5),
}

public enum InputEventIds {
    JUMP,
    LEFT,
    RIGHT,
    USE,
    SPECIAL_JUMP,
    SPECIAL_DUCK
}

public enum InputEventIds
{
    JUMP,
    LEFT,
    RIGHT,
    USE,
    SPECIAL_JUMP,
    SPECIAL_DUCK
}

Teste

Há duas maneiras de testar se o SDK de entrada foi implementado corretamente. Abra o SDK na IU do Google Play Games para ver o que um jogador pode ver ou no adb shell para testes e verificações automatizados.

Interface do usuário

Para testar na IU do Google Play Games, pressione Shift + Tab para abrir o Painel de jogo. No painel, clique em Controles para visualizar a lista de controles vinculados no momento.

Linha de comando

As entradas também podem ser verificadas pelo adb na linha de comando, o que pode ajudar nos testes automatizados do recurso.

Para ver o mapa de entrada atual, use o comando adb shell abaixo (substitua MY.PACKAGE.NAME pelo nome do jogo):

adb shell dumpsys input_mapping_service --get MY.PACKAGE.NAME

Você vai ver uma saída semelhante a esta se tiver registrado o InputMap:

Getting input map for com.example.inputsample...
Successfully received the following inputmap:
# com.google.android.libraries.play.games.InputMap@d73526e1
input_groups {
  group_label: "Basic Movement"
  input_actions {
    action_label: "Jump"
    input_controls {
      keycodes: 51
      keycodes: 19
    }
    unique_id: 0
  }
  input_actions {
    action_label: "Left"
    input_controls {
      keycodes: 29
      keycodes: 21
    }
    unique_id: 1
  }
  input_actions {
    action_label: "Right"
    input_controls {
      keycodes: 32
      keycodes: 22
    }
    unique_id: 2
  }
  input_actions {
    action_label: "Use"
    input_controls {
      keycodes: 33
      keycodes: 66
      mouse_actions: MOUSE_LEFT_CLICK
      mouse_actions_value: 0
    }
    unique_id: 3
  }
}
input_groups {
  group_label: "Special Input"
  input_actions {
    action_label: "Jump"
    input_controls {
      keycodes: 51
      keycodes: 19
      keycodes: 62
      mouse_actions: MOUSE_LEFT_CLICK
      mouse_actions_value: 0
    }
    unique_id: 4
  }
  input_actions {
    action_label: "Duck"
    input_controls {
      keycodes: 47
      keycodes: 20
      keycodes: 113
      mouse_actions: MOUSE_RIGHT_CLICK
      mouse_actions_value: 1
    }
    unique_id: 5
  }
}
mouse_settings {
  allow_mouse_sensitivity_adjustment: true
  invert_mouse_movement: true
}

Sincronizar mudanças na vinculação de teclas

Muitos jogos permitem que os jogadores personalizem as vinculações de teclas. Portanto, verifique se os dados retornados por InputMapProvider estão atualizados com as configurações atuais do jogador. Se necessário, você pode chamar registerInputMappingProvider em segurança com o mapa de entrada mais recente sempre que os jogadores mudarem o esquema de entrada.

Localização

O SDK de entrada não usa o sistema de localização do Android. Como resultado, é necessário fornecer strings localizadas ao enviar um InputMap. No entanto, isso também permite usar o sistema de localização do mecanismo do jogo.

Próxima etapa

Depois de integrar o SDK de entrada ao jogo, é possível continuar com todos os requisitos restantes do Google Play Games. Para mais informações, consulte Primeiros passos com o Google Play Games.