Passer à la version 1.1 du SDK Input pour Java et Kotlin

Ce guide explique comment passer de la version 1.0.0-beta du SDK Input pour Java et Kotlin à la version 1.1.0-beta pour votre jeu. Consultez le guide de mise à niveau Unity pour obtenir des instructions spécifiques à Unity.

Notes de version

Google Play Jeux sur PC permet de remapper les commandes du clavier en fonction des combinaisons de touches fournies par votre jeu à l'aide du SDK Input.

Pour accéder à cette fonctionnalité, ouvrez la superposition, sélectionnez les commandes, puis cliquez sur l'action à remapper.

Google Play Jeux sur PC mappe chaque entrée remappée par l'utilisateur avec l'entrée par défaut de votre jeu. Votre jeu n'a donc pas besoin de prendre en compte le remappage du joueur. Si vous avez besoin de connaître la nouvelle entrée correspondant à une action dans le jeu, comme l'affichage ds commandes du clavier dans le jeu, vous avez la possibilité d'enregistrer un rappel afin d'être averti des événements de remappage.

Google Play Jeux sur PC stocke localement les commandes remappées de chaque utilisateur afin qu'elles soient conservées entre les sessions de jeu. Étant donné qu'elles sont stockées localement, cela n'a aucune incidence sur l'expérience mobile et elles sont supprimées lors de la désinstallation de Google Play Jeux sur PC. Les paramètres des commandes ne sont pas conservés entre différents ordinateurs.

Vous n'avez pas besoin de mettre à niveau le SDK Input pour activer le remappage des touches dans le jeu. Toutefois, le remappage peut être désactivé pour votre jeu si une configuration non compatible est détectée.

Si vous souhaitez contrôler l'expérience de remappage des entrées ou si la fonctionnalité de remappage est désactivée pour votre jeu, procédez comme suit :

  • Installez le SDK Input 1.1.0-beta.
  • Mettez à jour les combinaisons de touches pour éviter les configurations non compatibles.
  • Mettez à jour votre InputMap pour définir la fonctionnalité de remappage comme activée.

Si vous souhaitez désactiver la fonctionnalité de remappage de votre jeu tout en affichant la version en lecture seule de vos combinaisons de touches, procédez comme suit :

  • Installez le SDK Input 1.1.0-beta.
  • Mettez à jour votre InputMap pour définir la fonctionnalité de remappage comme désactivée.

Vous pouvez mettre à niveau le SDK Input et installer la version 1.1.0-beta pour bénéficier des fonctionnalités de remappage avancées de Google Play Jeux sur PC. Pour cela, utilisez InputContexts afin de définir les commandes pour différentes scènes de votre jeu, d'ajouter des rappels pour écouter les événements de remappage, de définir un ensemble de touches réservées que l'utilisateur ne peut pas remapper et de désactiver la fonctionnalité de remappage par InputAction, InputGroup ou InputMap.

Tenez compte des exceptions suivantes lorsque vous passez à la nouvelle version du SDK :

Configurations non compatibles

Le remappage des entrées est désactivé si les conditions suivantes ne sont pas remplies :

  • Une InputAction qui utilise plusieurs touches doit être composée d'une touche de modification et d'une touche de non-modification. Par exemple, Maj+A est valide, mais A+B, Ctrl+Alt et Maj+A+Tabulation ne le sont pas.

  • Deux objets InputAction ou InputGroup ou plus ne peuvent pas partager le même ID unique.

Mettre à niveau

Le SDK Input 1.1.0-beta est rétrocompatible avec le SDK Input 1.0.0-beta. Les jeux qui utilisent des implémentations précédentes du SDK Input continuent à prendre en charge le remappage de base, sauf s'ils utilisent une configuration non compatible. Si votre jeu utilise une version précédente du SDK Input, envisagez de lire le guide de mise à niveau de la version 0.0.4 à la version 1.0.0-beta.

La mise à niveau vers la version 1.1.0-beta offre de nouvelles fonctionnalités :

Mettre à niveau la dépendance

Si vous utilisez Gradle pour importer le SDK Input, passez à la dernière version :

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

Définir des champs statiques

Pour la version 1.1.0-beta, il est recommandé de définir vos objets InputAction, InputGroup, InputContext et InputMap comme des champs statiques de la classe InputMappingProvider, car ils seront accessibles à partir d'autres sections de votre application :

Kotlin

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

Java

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

Mettre à jour vos actions d'entrée (InputActions)

La méthode InputAction.create() du SDK Input 1.0.0-beta est obsolète. Une InputAction possède désormais un identifiant de version et peut être marquée comme pouvant être remappée ou non. Une InputAction définie à l'aide de la méthode create() du SDK Input 1.0.0-beta peut être remappée par défaut et ne contient pas d'informations de gestion des versions :

InputAction dans le SDK Input 1.0.0-beta

Kotlin

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

Java

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

InputAction dans le SDK Input 1.1.0-beta

Kotlin

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
}

Java

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 dans le SDK Input 1.1.0-beta (avec chaîne de version)

Kotlin

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
)

Java

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

Pour en savoir plus sur la gestion des versions de combinaisons de touches, consultez la section Suivi des identifiants de touches.

Mettre à jour vos groupes d'entrées (InputGroups)

Dans le SDK Input 1.1.0-beta, vous devez identifier chaque InputGroup de manière unique. Chaque InputAction appartient à un InputGroup, c'est-à-dire un ensemble d'actions associées. Cela améliore la navigation et la visibilité des commandes pendant le jeu. Tout comme une InputAction doit avoir un identifiant unique entre toutes les actions d'un même InputContext, un InputGroup doit avoir un identifiant unique entre les différents groupes.

Pour les exemples de cette section, un jeu comporte deux objets InputContext représentant le menu principal et le jeu. Les ID appropriés sont suivis pour chaque InputGroup dans ces contextes à l'aide de l'énumération suivante :

Kotlin

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
}

Java

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
}

Comme pour InputAction, la méthode InputGroup.create() du SDK Input 1.0.0-beta a été abandonnée. Vous devez mettre à jour votre InputGroup dans votre jeu avec un identifiant de version et une valeur booléenne indiquant si les objets InputAction de vos groupes peuvent être remappés. Les groupes créés avec la méthode obsolète create() du SDK Input 1.0.0-beta peuvent être remappés, avoir l'ID 0, avec l'ID de version correspondant à une chaîne vide ("") :

InputGroup dans le SDK Input 1.0.0-beta

Kotlin

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

Java

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

InputGroup dans le SDK Input 1.1.0-beta

Kotlin

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

Java

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 dans le SDK Input 1.1.0-beta (avec chaîne de version)

Kotlin

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

Java

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

Pour en savoir plus sur la gestion des versions de combinaisons de touches, consultez la section Suivi des identifiants de touches.

Mettre à jour votre mappage des entrées (InputMap)

La méthode InputMap.create() du SDK Input 1.0.0-beta est obsolète. Mettez à jour InputMap pour attribuer un identifiant de version, désactiver complètement la fonctionnalité de remappage ou attribuer une liste de touches réservées à votre jeu que vous ne souhaitez pas que l'utilisateur remappe. Chaque InputMap défini à l'aide de la méthode create() du SDK Input 1.0.0-beta peut être remappé par défaut, est identifié par l'ID 0 et ne compte aucune touche réservée.

InputMap dans le SDK Input 1.0.0-beta

Kotlin

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

Java

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

InputMap dans le SDK Input 1.1.0-beta

Kotlin

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

Java


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

Étapes suivantes

Poursuivez la mise à niveau vers la version 1.1.0-beta en attribuant différentes commandes pour différentes scènes à l'aide d'InputContexts ou en mettant à jour l'UI de votre jeu via des notifications sur le remappage des événements reçues à l'aide d'InputRemappingListeners.

Lors de la mise à jour de vos combinaisons de touches, consultez ces bonnes pratiques, et tenez compte des restrictions et des limites de la fonctionnalité de remappage.