Cómo comenzar a utilizar el SDK de entrada

En este tema, se describe cómo configurar y mostrar la superposición del SDK de entrada en los juegos compatibles con Google Play Juegos. Las tareas incluyen agregar el SDK a tu juego y generar un mapa de entrada, que contiene la acción del juego para las asignaciones de entradas del usuario Para los juegos que admiten cambios de vinculación de teclas, también debes realizar un seguimiento de los cambios y sincronizarlos con el SDK.

Antes de comenzar

Antes de incorporar el SDK de entrada a tu juego, debes agregar compatibilidad con el teclado y el mouse.

Cómo agregar el SDK

Para obtener el SDK de entrada para Java o Kotlin, agrega una dependencia al archivo build.gradle del nivel de módulo (es probable que esté en tu directorio app):

dependencies {
  implementation 'com.google.android.libraries.play.games:inputmapping:1.0.0-beta'
  ...
}

El SDK de entrada para Unity aún no está disponible para descargar. Estará disponible como unitypackage y tgz para desarrolladores de Unity.

Recuerda expresar tu interés en ser uno de los primeros en acceder al SDK nuevo.

Cómo generar la asignación de entrada

La asignación de entrada representa acciones de juego para asignaciones de entradas de usuarios a fin de que se muestren en la superposición del SDK de entrada. Para generar la asignación de entrada, debes compilar un InputMap y, luego, mostrarlo con un InputMappingProvider.

A continuación, se muestra un esquema de ejemplo de un InputMappingProvider:

Kotlin

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

Java

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

C#

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

En las siguientes secciones, se describe cómo crear un InputMap para mostrar desde tu InputMappingProvider.

Cómo definir una acción de entrada

La clase InputAction se usa para asignar una tecla o una combinación de teclas a una acción del juego.

En este ejemplo, se asigna la tecla barra espaciadora a la acción de salto:

Kotlin

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

Java

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

C#

var jumpInputAction = PlayInputAction.Create(
    "Jump",
    (int)InputEventIds.Jump,
    PlayInputControls.Create(
        new[]
        {
            AndroidKeyCode.KEYCODE_SPACE
        },
        null
    )
);

Captura de pantalla de la superposición de entrada que indica que la acción de salto está vinculada a la tecla barra espaciadora.

Las acciones también pueden representar entradas de mouse. En este ejemplo, se configura el clic derecho para la acción de movimiento:

Kotlin

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

Java

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

C#

var cmbMove = PlayInputAction.Create(
    "Move",
    (int)InputEventIds.CmbMove,
    PlayInputControls.Create(
        null,
        new[]
        {
            PlayMouseAction.MouseRightClick
        }
    )
);

Captura de pantalla de la superposición de entrada en la que la acción de movimiento está vinculada al clic derecho.

Las combinaciones de teclas se especifican cuando pasas varios códigos de tecla a InputAction. En este ejemplo, se asignan la barra espaciadora + Mayúsculas a la acción de correr, que funciona incluso cuando la tecla barra espaciadora está asignada al salto.

Kotlin

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

Java

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

C#

var cmbDash = PlayInputAction.Create(
    "Dash",
    (int)InputEventIds.CmbDash,
    PlayInputControls.Create(
        new[]
        {
            AndroidKeyCode.KEYCODE_SPACE, AndroidKeyCode.KEYCODE_SHIFT_LEFT
        }, null
    )
);

Captura de pantalla de la superposición de entrada, donde Mayúsculas + barra espaciadora están vinculadas a la acción de correr.

El SDK de entrada te permite combinar los botones del mouse y las teclas para un solo comando. En este ejemplo, se indica que Mayúsculas y clic derecho presionados juntos agregan un punto de referencia en este juego:

Kotlin

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

Java

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

C#

var cmbWaypoint = PlayInputAction.Create(
    "Add Waypoint",
    (int)InputEventIds.CmbWaypoint,
    PlayInputControls.Create(
        new[]
        {
            AndroidKeyCode.KEYCODE_SHIFT_LEFT
        },
        new[]
        {
            PlayMouseAction.MouseRightClick
        }
    )
);

Captura de pantalla de la superposición de entrada donde la acción Agregar punto de referencia está vinculada a Mayúsculas + clic derecho.

En esta sección, se describen los métodos a los que se llamó en el ejemplo de código:

Kotlin

InputAction.create tiene estos parámetros:

  • actionLabel es la string que se muestra en la IU para representar esta acción. La localización no se realiza automáticamente, por lo que depende de ti realizar la localización por adelantado.
  • uniqueId es un ID de número entero que identifica esta acción. Cada acción debe tener un identificador único coherente. En este ejemplo, se usa una enumeración. Consulta Cómo realizar un seguimiento de los ID de teclas para obtener más información.
  • inputControls define los controles de entrada que usa la acción. Estos se asignarán a glifos coherentes en la interfaz de usuario.

InputControls.create crea las entradas asociadas con una acción. Los parámetros son los siguientes:

  • keycodes es una lista de números enteros que representan las entradas del teclado que se asocian con una acción. Estas se definen en la clase KeyEvent.
  • mouseActions es una lista de números enteros que representa las entradas del mouse que se asocian con la acción. Estas se definen en el mismo parámetro InputControls.

Java

InputAction.create tiene estos parámetros:

  • actionLabel es la string que se muestra en la IU para representar esta acción. La localización no se realiza automáticamente, por lo que depende de ti realizar la localización por adelantado.
  • uniqueId es un ID de número entero que identifica esta acción. Cada acción debe tener un identificador único coherente. En este ejemplo, se usa una enumeración. Consulta Cómo realizar un seguimiento de los ID de teclas para obtener más información.
  • inputControls define los controles de entrada que usa la acción. Estos se asignarán a glifos coherentes en la interfaz de usuario.

InputControls.create crea las entradas asociadas con una acción. Los parámetros son los siguientes:

  • keycodes es una lista de números enteros que representan las entradas del teclado que se asocian con una acción. Estas se definen en la clase KeyEvent.
  • mouseActions es una lista de números enteros que representa las entradas del mouse que se asocian con esta acción. Estas se definen en el mismo parámetro InputControls.

C#

InputAction tiene estos campos:

  • ActionLabel es la string que se muestra en la IU para representar esta acción. La localización no se realiza automáticamente, por lo que depende de ti realizar la localización por adelantado.
  • UniqueId es un ID de número entero que identifica esta acción. Cada acción debe tener un identificador único coherente, por ello en este ejemplo se usa una enumeración. Consulta Cómo realizar un seguimiento de los ID de teclas.
  • InputControls define los controles de entrada que usa esta acción. Estos se asignarán a glifos coherentes en la interfaz de usuario.

InputControls representa las entradas asociadas con una acción. Tiene los siguientes campos:

  • AndroidKeycodes es una lista de números enteros que representan las entradas del teclado que se asocian con una acción. Estas se definen en la clase AndroidKeycode.
  • MouseActions es una lista de valores MouseAction que representan entradas del mouse que se asocian con esta acción.

Cómo definir un grupo de entrada

Un InputGroup es un grupo de objetos InputAction similares. Por ejemplo:

  • Puedes especificar diferentes conjuntos de entradas para navegar por los menús en comparación con moverte en el juego.
  • Puedes especificar diferentes entradas de conjuntos según el modo de locomoción en el juego, como conducir o caminar.
  • Puedes especificar diferentes conjuntos de entradas según el estado actual del juego, como explorar un inframundo en comparación con recorrer un nivel particular.

Si organizas las entradas en grupos, permites que un jugador encuentre la vinculación correcta de teclas para su situación actual con mayor facilidad.

Kotlin

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

Java

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

C#

var movementInputGroup = PlayInputGroup.Create(
    "Basic Movement",
    new[]
    {
        jumpInputAction, leftInputAction, rightInputAction, useInputAction
    }
);

En esta sección, se describen las llamadas de métodos utilizadas en el ejemplo de código:

Kotlin

InputGroup.create tiene estos parámetros:

  • groupLabel es una string que se muestra en la IU y se puede usar para agrupar un conjunto de acciones de forma lógica. Esta string no se localiza para ti.
  • inputActions es una lista de objetos InputAction que definiste en el último paso. Todas estas acciones se mostrarán, de forma visual, bajo el encabezado de este grupo.

Java

InputGroup.create tiene estos parámetros:

  • groupLabel es una string que se muestra en la IU y se puede usar para agrupar un conjunto de acciones de forma lógica. Esta string no se localiza para ti.
  • inputActions es una lista de objetos InputAction que definiste en el último paso. Todas estas acciones se mostrarán, de forma visual, bajo el encabezado de este grupo.

C#

InputGroup tiene estos campos:

  • GroupLabel es una string que se muestra en la IU y se puede usar para agrupar un conjunto de acciones de forma lógica. Esta string no se localiza para ti.
  • InputActions es una lista de objetos InputAction que definiste en el último paso. Todas estas acciones se mostrarán, de forma visual, bajo el encabezado de este grupo.

Cómo crear un mapa de entrada

Un InputMap es una colección de todos los objetos InputGroup disponibles en un juego y, por lo tanto, todos los objetos InputAction que un jugador puede esperar realizar.

En el siguiente ejemplo, los objetos MovementInputGroup se agrupan con objetos MouseSettings. Los objetos MouseSettings indican que la sensibilidad del mouse se puede ajustar y que el mouse se invierte en el eje y:

Kotlin

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

Java

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

C#

return PlayInputMap.Create(
    new[]
    {
        movementInputGroup, specialInputGroup, combinationInputGroup
    },
    PlayMouseSettings.Create(true, false)
);

Cómo enviar un mapa de entrada

Una vez que se escribió un InputMapProvider para un juego que muestra un InputMap válido, se debe registrar con el SDK de entrada. Si las entradas de un juego nunca cambian, esto solo se debe hacer una vez durante la vida útil de un juego, ya que el InputMapProvider no se ve afectado por los eventos de ciclo de vida de Android.

Kotlin

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

    val inputMappingClient = Input.getInputMappingClient(this)
    inputMappingClient.setInputMappingProvider(MyInputMapProvider())
}

Java

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

    InputMappingClient inputMappingClient = Input.getInputMappingClient(this);
    inputMappingClient.setInputMappingProvider(new MyInputMapProvider());
}

C#

void Start()
{
    _inputMappingProvider = new MyInputMappingProvider();
    PlayInput.GetInputMappingClient().SetInputMappingProvider(_inputMappingProvider);
}

Aunque el SDK es lo suficientemente inteligente para evitar el filtrado de recursos si no lo haces, debes cancelar el registro del proveedor de la asignación de entradas cuando el juego esté terminado.

Kotlin

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

    super.onDestroy()
}

Java

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

    super.onDestroy();
}

C#

private void OnDestroy()
{
    PlayInput.GetInputMappingClient().ClearInputMappingProvider();
}

Cómo hacer un seguimiento de ID de teclas

Debes realizar un seguimiento de los ID únicos para cada InputAction que definas. La siguiente enumeración realiza un seguimiento de los ID únicos para todos los ejemplos de este tema. Como los ID se usan para realizar un seguimiento de los cambios de teclas, no uses un hash del nombre de la acción localizado.

Kotlin

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

Java

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

C#

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

Probar

Hay dos maneras de probar si el SDK de entrada se implementó correctamente. Puedes abrirlo en la IU de Google Play Juegos a fin de saber qué podría ver un jugador o en adb shell para pruebas automatizadas y verificación.

Interfaz de usuario

Si quieres realizar una prueba en la IU de Google Play Juegos, presiona Mayúsculas + Tab para abrir el Panel de juego. Desde el panel, haz clic en Controles para ver la lista de controles vinculados en ese momento.

Imagen que ilustra el flujo descrito más arriba. Mayús + Tab abre el Panel de juego. A continuación, si haces clic en "Controles", se abrirá la superposición de controles. Esta superposición muestra un grupo que se llama "Movimiento básico" con acciones como "Saltar", "Izquierda" y "Derecha" en él. Cada control muestra las acciones que se realizan según cada uno de ellos. Por ejemplo, "Saltar" tiene el texto "Tecla W + Tecla arriba" escrito debajo. Luego, a su derecha, hay una imagen grande de una tecla con "w" y una con "arriba" en ella. También hay una sección llamada "Entrada especial" en la que aparece "Agacharse".

Línea de comandos

Las entradas también se pueden verificar a través de adb en la línea de comandos, lo que puede ayudar con las pruebas automatizadas de la función.

Para obtener el mapa de entrada actual, usa el siguiente comando de adb shell (reemplaza MY.PACKAGE.NAME por el nombre de tu juego):

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

Si registraste correctamente tu InputMap, verás un resultado como el siguiente:

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
}

Cómo sincronizar cambios de vinculación de teclas

Muchos juegos permiten que los jugadores personalicen sus vinculaciones de teclas. Por lo tanto, debes asegurarte de que los datos que muestres en InputMapProvider estén actualizados para la configuración actual del jugador. Si es necesario, puedes llamar de forma segura a setInputMappingProvider con el mapa de entrada más reciente cada vez que los jugadores terminen de cambiar el esquema de entrada.

Localización

El SDK de entrada no usa el sistema de localización de Android. Como resultado, debes proporcionar strings localizadas cuando envíes un InputMap. Sin embargo, esto también te permite usar el sistema de localización del motor de tu juego.

Siguiente paso

Después de integrar el SDK de entrada en el juego, puedes continuar con los requisitos restantes de Google Play Juegos. Para obtener más información, consulta Cómo comenzar a usar Google Play Juegos.