Esegui l'upgrade dell'SDK di input per Java e Kotlin alla versione 1.1

Questa guida spiega come eseguire l'upgrade del gioco dall'SDK Input 1.0.0-beta per Java e Kotlin alla versione 1.1.1-beta. Consulta la guida all'upgrade di Unity per istruzioni specifiche per Unity.

Note di rilascio

Google Play Giochi su PC supporta la rimappatura dei controlli della tastiera in base alle assegnazioni dei tasti fornite dal gioco utilizzando l'SDK Input.

Gli utenti accedono a questa funzionalità aprendo l'overlay, selezionando i controlli e poi facendo clic sull'azione che vogliono rimappare.

Google Play Games su PC mappa ogni input rimappato dall'utente sull'input predefinito del gioco. In questo modo, il gioco non deve tenere conto della rimappatura del giocatore. Se devi conoscere il nuovo input per un'azione in-game, ad esempio la visualizzazione dei controlli da tastiera nel gioco, puoi registrare facoltativamente un callback per ricevere una notifica per gli eventi di rimappatura.

Google Play Giochi su PC memorizza localmente i controlli rimappati di ogni utente, in modo che rimangano invariati durante le sessioni di gioco. Poiché questi dati vengono memorizzati localmente, non influiscono sull'esperienza mobile e vengono eliminati quando Google Play Giochi su PC viene disinstallato. Le impostazioni di controllo non vengono mantenute su più dispositivi PC.

Non è necessario eseguire l'upgrade dell'SDK Input per abilitare la rimappatura dei tasti nel gioco, ma la rimappatura può essere disattivata per il gioco se viene rilevata una configurazione non supportata.

Se vuoi controllare l'esperienza di rimappatura degli input o se la funzionalità di rimappatura è disattivata per il tuo gioco, segui questi passaggi per risolvere il problema:

  • Esegui l'upgrade all'SDK Input 1.1.1-beta.
  • Aggiorna le combinazioni di tasti per evitare le configurazioni non supportate.
  • Aggiorna il tuo InputMap per impostare la funzionalità di rimappatura attivata.

Se vuoi disattivare la funzionalità di rimappatura per il tuo gioco e visualizzare comunque la versione di sola lettura delle associazioni di tasti, segui questi passaggi:

  • Esegui l'upgrade all'SDK Input 1.1.1-beta.
  • Aggiorna il tuo InputMap per impostare la funzionalità di rimappatura su disattivata.

Puoi eseguire l'upgrade della tua versione dell'SDK Input a 1.1.1-beta per sfruttare le funzionalità avanzate di rimappatura in Google Play Giochi su PC utilizzando InputContexts per definire i controlli per diverse scene del gioco, aggiungere callback per rilevare gli eventi di rimappatura, definire un insieme di tasti riservati a cui l'utente non può rimappare e disattivare la funzionalità di rimappatura per InputAction, InputGroup o InputMap.

Tieni presente le seguenti eccezioni durante l'upgrade alla nuova versione dell'SDK:

Configurazioni non supportate

La rimappatura dell'input è disattivata se non sono soddisfatte le seguenti condizioni:

  • Un InputAction che utilizza più tasti deve essere composto da un tasto di modifica e da un tasto non di modifica. Ad esempio, Maiusc+A è valido, ma A+ B, Ctrl+Alt e Maiusc+A+Tab non lo sono.

  • Due o più oggetti InputAction o InputGroup non possono condividere lo stesso ID univoco.

Esegui l'upgrade

L'SDK Input 1.1.1-beta è compatibile con le versioni precedenti dell'SDK Input 1.0.0-beta. I giochi che utilizzano implementazioni precedenti dell'SDK Input supportano ancora la rimappatura di base, a meno che non utilizzino una configurazione non supportata. Se il tuo gioco utilizza una versione precedente dell'SDK Input, ti consigliamo di leggere la guida all'upgrade dalla versione 0.0.4 alla 1.0.0-beta.

L'upgrade alla versione 1.1.1-beta attiva nuove funzionalità, tra cui:

Esegui l'upgrade della dipendenza

Se utilizzi Gradle per importare l'SDK Input, esegui l'upgrade all'ultima versione:

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

Definisci i campi statici

Per la versione 1.1.1-beta è consigliabile definire gli oggetti InputAction, InputGroup, InputContext e InputMap come campi statici della classe InputMappingProvider, poiché questi campi sono accessibili da altre parti dell'applicazione:

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

Aggiornare InputActions

Il metodo InputAction.create() dell'SDK Input 1.0.0-beta è deprecato. Un InputAction ora ha un identificatore di versione e può essere contrassegnato come rimappabile o meno. Un InputAction definito utilizzando il metodo Input SDK 1.0.0-beta create() è rimappabile per impostazione predefinita e non contiene informazioni sul controllo delle versioni:

InputAction nell'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 nell'SDK Input 1.1.1-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 in Input SDK 1.1.1-beta (con stringa di versione)

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

Per saperne di più sul controllo delle versioni delle associazioni di tasti, vedi Monitoraggio degli ID chiave.

Aggiornare InputGroups

In Input SDK 1.1.1-beta devi identificare in modo univoco ogni InputGroup. Ogni InputAction appartiene a un InputGroup, ovvero una raccolta di azioni correlate. In questo modo, la navigazione e la visibilità dei controlli durante il gameplay migliorano. Allo stesso modo in cui InputAction deve avere un identificatore univoco tra tutte le azioni in un singolo InputContext, un InputGroup deve avere un ID univoco tra i gruppi esistenti.

Per gli esempi in questa sezione, un gioco ha due oggetti InputContext che rappresentano il menu principale e il gameplay. Gli ID appropriati vengono monitorati per ogni InputGroup in questi contesti utilizzando la seguente enumerazione:

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
}

Come InputAction, il metodo InputGroup.create() dell'SDK Input 1.0.0-beta è stato ritirato. Devi aggiornare InputGroup nel gioco con un identificatore di versione e un valore booleano che indica se gli oggetti InputAction nei gruppi sono rimappabili. I gruppi creati con il metodo 1.0.0-beta create() dell'SDK Input deprecato sono rimappabili, hanno l'ID 0 e l'ID versione è una stringa vuota (""):

InputGroup nell'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 nell'SDK Input 1.1.1-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 nell'SDK Input 1.1.1-beta (con stringa di versione)

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

Per saperne di più sul controllo delle versioni delle associazioni di tasti, vedi Monitoraggio degli ID chiave.

Aggiorna InputMap

Il metodo InputMap.create() dell'SDK Input 1.0.0-beta è deprecato. Aggiorna il tuo InputMap per assegnare un identificatore di versione, disattivare completamente la funzionalità di rimappatura o assegnare un elenco di tasti riservati per il tuo gioco che non vuoi che vengano utilizzati per la rimappatura da parte dell'utente. Ogni InputMap definito utilizzando il metodo 1.0.0-beta create() dell'SDK Input è rimappabile per impostazione predefinita, è identificato con l'ID 0 e non ha tasti riservati.

InputMap nell'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 in Input SDK 1.1.1-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()
                )
        )
);

Passaggi successivi

Continua l'upgrade alla versione 1.1.1-beta Assegnando controlli diversi per scene diverse utilizzando InputContexts o aggiornando la UI del gioco Ricevendo notifiche sugli eventi di rimappatura utilizzando InputRemappingListeners.

Quando aggiorni le assegnazioni dei tasti, dai un'occhiata alle best practice per la progettazione delle assegnazioni dei tasti e considera le limitazioni e restrizioni della funzionalità di riassegnazione.