Cómo actualizar el SDK de entrada para Unity a la versión 1.1

En esta guía, se explica cómo actualizar tu juego de la versión 1.0 a la versión 1.1 del SDK de entrada para Unity. Haz clic aquí para obtener instrucciones sobre Java y Kotlin.

Notas de la versión

Google Play Juegos para PC admite la reasignación de los controles del teclado según las combinaciones de teclas que proporciona tu juego con el SDK de entrada.

Para acceder a esta función, los usuarios deben abrir la superposición, seleccionar los controles y hacer clic en la acción que desean reasignar.

Google Play Juegos para PC asigna todas las entradas que volvió a asignar el usuario a la entrada predeterminada del juego. De esta manera, el juego no tiene que estar al tanto de la reasignación del jugador. Si necesitas conocer la nueva entrada para una acción en el juego, como mostrar los controles del teclado, puedes registrar una devolución de llamada para que se te notifique cuando se vuelvan a asignar los eventos.

Google Play Juegos para PC almacena los controles reasignados de cada usuario de forma local para que sean persistentes en todas las sesiones. Como esta configuración se almacena de forma local, no influye en la experiencia en dispositivos móviles y se borra cuando se desinstala Google Play Juegos para PC. Las opciones de configuración no persisten en varios dispositivos de PC.

No es necesario que actualices el SDK de entrada para habilitar la reasignación de teclas en el juego, pero sí puedes inhabilitar la reasignación si se detecta una configuración no admitida.

Si deseas controlar la experiencia de reasignación de entrada o si la función está inhabilitada en tu juego, sigue estos pasos:

  • Actualiza al SDK de entrada 1.1.1-beta.
  • Actualiza las vinculaciones de teclas para evitar las configuraciones no admitidas.
  • Actualiza tu InputMap para configurar la función de reasignación habilitada.

Si deseas inhabilitar la función de reasignación de tu juego y mostrar la versión de solo lectura de las vinculaciones de teclas, sigue estos pasos:

  • Actualiza al SDK de entrada 1.1.1-beta.
  • Actualiza tu InputMap para establecer la función de reasignación en inhabilitada.

Puedes actualizar tu versión del SDK de entrada a 1.1.1-beta para aprovechar las funciones de reasignación avanzadas de Google Play Juegos para PC. Para ello, usa InputContexts para definir controles en diferentes escenas del juego, agrega devoluciones de llamada para escuchar eventos de reasignación, define un conjunto de teclas reservadas a las que el usuario no puede reasignar e inhabilita la función de reasignación en InputAction, InputGroup o InputMap.

Cuando realices la actualización, ten en cuenta las siguientes excepciones:

Opciones de configuración no compatibles

La reasignación de entrada se inhabilita si no se cumplen las siguientes condiciones:

  • Una InputAction que usa varias teclas debe constar de una teclas modificadora y no modificadora. Por ejemplo, Mayúsculas + A es válida, pero A + B, Ctrl + Alt y Mayúsculas + A + Tab no lo son.

  • Dos o más objetos InputAction o InputGroup no pueden compartir el mismo ID único.

Presentamos InputContext

Un elemento InputContext permite que un juego use la misma tecla para diferentes acciones en el juego sin conflictos. De esta manera, si un juego usa la barra espaciadora para saltar durante el juego y para confirmar una selección del menú, los jugadores pueden reasignar de manera individual la barra espaciadora y cambiarla por la tecla Intro en los menús y cambiar la barra espaciadora por la flecha hacia arriba durante el juego.

En el siguiente diagrama de secuencias, se muestra cómo funciona la API de setInputContext() en el tiempo de ejecución:

Diagrama que muestra el flujo del SDK de entrada cuando se vuelven a asignar teclas

Actualización

Los juegos que usan implementaciones anteriores del SDK de entrada aún admiten la reasignación básica, a menos que usen una configuración no admitida. Si tu juego usa una versión anterior del SDK de entrada, te recomendamos leer la guía de actualización de 0.0.4 a 1.0.0-beta.

La actualización a la versión 1.1.1-beta habilita nuevas funciones, incluidas las siguientes:

  • Activar cambios de contexto
  • Recibir notificaciones de eventos de asignación de teclas
  • Inhabilitar la reasignación por acción, grupo, contexto o mapa

Instalación

La versión v1.1.1-beta del complemento de Unity está disponible para su uso. Debes borrar las versiones anteriores del SDK de entrada instaladas en el juego y actualizar a la versión actual.

Para agregar la versión 1.1.1-beta del SDK de entrada a tu juego, consulta Cómo agregar el SDK.

Cómo definir campos estáticos

Para la versión 1.1.1-beta, se recomienda definir los objetos InputActions, InputGroups, InputContexts y InputMap como campos estáticos de tu clase InputMappingProvider, ya que se puede acceder a estos campos desde otras partes de la aplicación:

#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

Cómo actualizar tus InputActions

El método InputAction.create() del SDK de entrada 1.0.0-beta dejó de estar disponible. Una InputAction ahora tiene un identificador de versión y se puede marcar como reasignable o no. Una InputAction definida con el método create() de 1.0.0-beta del SDK de entrada se puede reasignar de forma predeterminada y carece de información sobre el control de versiones:

InputAction en el 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 en el 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 en el SDK de entrada 1.1.1-beta (con cadena de versión)

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 obtener más información sobre el control de versiones de tus vinculaciones de teclas, consulta Cómo realizar un seguimiento de los ID de teclas.

Cómo actualizar tus InputGroups

En el SDK de entrada 1.1.1-beta, debes identificar cada InputGroup de forma única. Cada InputAction pertenece a InputGroup, una recopilación de acciones relacionadas. Esto mejora la navegación y la visibilidad de los controles durante el juego. De la misma manera que InputAction debe tener un identificador único entre todas las acciones de un solo InputContext, un InputGroup debe tener un ID único en todo los grupos existentes.

Para los ejemplos de esta sección, un juego tiene dos objetos InputContext que representan el menú principal y el juego. Se realiza un seguimiento de los IDs adecuados para cada InputGroup en estos contextos a través de la siguiente enumeración:

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
}

Al igual que InputAction, dejó de estar disponible el método InputGroup.create() del SDK de entrada 1.0.0-beta. Debes actualizar el objeto InputGroup de tu juego con un identificador de versión y un valor booleano que indique si los objetos InputAction de tus grupos son reasignables. Los grupos creados con el método create() del SDK de entrada 1.0.0-beta que dejó de estar disponible son reasignables, tienen el ID 0 y el ID de versión es una string vacía (""):

InputGroup en el SDK de entrada 1.0.0-beta

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

InputGroup en el 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 en el SDK de entrada 1.1.1-beta (con cadena de versión)

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 obtener más información sobre el control de versiones de tus vinculaciones de teclas, consulta Cómo realizar un seguimiento de los ID de teclas.

Cómo actualizar tu InputMap

El método InputMap.create() del SDK de entrada 1.0.0-beta dejó de estar disponible. Actualiza tu InputMap para asignar un identificador de versión, inhabilitar por completo la función de reasignación o asignar una lista de teclas reservadas para tu juego que no deseas que el usuario vuelva a asignar. Cada InputMap definido con el método create() del SDK de entrada 1.0.0-beta se puede volver a asignar de forma predeterminada, se identifica con el ID 0 y no tiene ninguna tecla reservada.

InputMap en el SDK de entrada 1.0.0-beta

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

InputMap en el 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()
);

Próximos pasos

Continúa con la actualización a la versión 1.1.1-beta. Para ello, asigna distintos controles para diferentes escenas mediante InputContexts o actualiza la IU del juego para recibir notificaciones sobre los eventos de asignación con InputRemappingListeners.

Cuando actualices tus vinculaciones de teclas, consulta las prácticas recomendadas para diseñar vinculaciones de teclas y ten en cuenta las restricciones y limitaciones de la función de reasignación.