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

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

Note sulla versione

Google Play Giochi su PC supporta la rimappatura dei controlli da tastiera in base alle associazioni di tasti fornite dal tuo gioco utilizzando l'SDK di immissione.

Per accedere a questa funzionalità, gli utenti aprono l'overlay, selezionano i controlli e fanno clic sull'azione da rimappare.

Google Play Giochi su PC mappa ogni input rimappato dall'utente sull'input predefinito del gioco. In questo modo il gioco non deve essere a conoscenza della rimappatura del giocatore. Se vuoi conoscere il nuovo input per un'azione in-game, ad esempio la visualizzazione dei controlli da tastiera nel gioco, puoi facoltativamente registrare un callback per ricevere una notifica per la nuova mappatura degli eventi.

Google Play Giochi su PC archivia localmente i controlli rimappati di ogni utente in modo che siano permanenti tra le sessioni di gioco. Poiché viene archiviata in locale, non influisce sull'esperienza sui dispositivi mobili e viene eliminata dopo la disinstallazione di Google Play Giochi su PC. Le impostazioni di controllo non vengono salvate in modo permanente su più PC.

Non è necessario eseguire l'upgrade dell'SDK di immissione per attivare la rimappatura delle chiavi nel gioco, ma la nuova mappatura può essere disattivata per il gioco se viene rilevata una configurazione non supportata.

Se vuoi controllare l'esperienza di rimappatura dell'input o se la relativa funzionalità è disabilitata per il tuo gioco, svolgi i passaggi che seguono per risolvere il problema:

• Esegui l'upgrade all'SDK di input 1.1.0-beta.
• Aggiorna le associazioni di chiavi per evitare le configurazioni non supportate.
• Aggiorna InputMap per impostare la funzionalità di rimappatura come attivata.

Se vuoi disattivare la funzionalità di rimappatura per il gioco pur continuando a visualizzare la versione di sola lettura delle associazioni di tasti, procedi nel seguente modo:

• Esegui l'upgrade all'SDK di input 1.1.0-beta.
• Aggiorna InputMap per impostare la funzionalità di rimappatura su disattivata.

Puoi eseguire l'upgrade della tua versione dell'SDK di input a 1.1.0-beta per sfruttare le funzionalità di remapping avanzate in Google Play Giochi su PC utilizzando InputContexts per definire i controlli per le diverse scene del gioco, aggiungere callback per ascoltare eventi di rimappatura, definire un set di chiavi riservate che 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 degli input è disabilitata se le seguenti condizioni non sono soddisfatte:

• Un InputAction che utilizza più tasti deve essere composto da un tasto di modifica e un tasto non di modifica. Ad esempio, Maiusc + A è valido, mentre 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.

Upgrade

L'SDK di input 1.1.0-beta è compatibile con le versioni precedenti dell'SDK di input 1.0.0-beta. I giochi che utilizzano implementazioni precedenti dell'SDK di 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 di input, ti consigliamo di leggere la guida all'upgrade dalla versione 0.0.4 alla versione 1.0.0-beta.

L'aggiornamento alla versione 1.1.0-beta attiva nuove funzionalità, tra cui:

• Attivazione dei cambiamenti di controllo delle scene.
• Ricezione di notifiche relative agli eventi di mappatura principali.
• È in corso la disattivazione della rimappatura per azione, gruppo, contesto o mappa.

Esegui l'upgrade della dipendenza

Se utilizzi Gradle per importare l'SDK di input, esegui l'upgrade alla versione più recente:

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

Definisci campi statici

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

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

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

Aggiorna InputActions

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

InputAction nell'SDK di input 1.0.0-beta

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

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

InputAction nell'SDK di input 1.1.0-beta

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
}

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 nell'SDK di input 1.1.0-beta (con stringa di versione)

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
)

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 ulteriori informazioni sul controllo delle versioni delle associazioni di chiavi, consulta ID chiavi di monitoraggio.

Aggiorna i tuoi InputGroups

Nell'SDK di input 1.1.0-beta devi identificare in modo univoco ogni InputGroup. Ogni InputAction appartiene a un InputGroup, una raccolta di azioni correlate. Questo migliora la navigazione e la rilevabilità dei controlli durante il gameplay. 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 in tutti 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:

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
}

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 di input 1.0.0-beta è stato deprecato. Devi aggiornare InputGroup nel gioco con un identificatore di versione e un valore booleano che indicano se gli oggetti InputAction nei gruppi sono rimappabili. I gruppi creati con il metodo create() dell'SDK di input 1.0.0-beta deprecato sono rimappabili, hanno l'ID 0 e l'ID versione è una stringa vuota (""):

InputGroup in Input SDK 1.0.0-beta

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

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

InputGroup in Input SDK 1.1.0-beta

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

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 in Input SDK 1.1.0-beta (con stringa di versione)

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

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 ulteriori informazioni sul controllo delle versioni delle associazioni di chiavi, consulta ID chiavi di monitoraggio.

Aggiorna InputMap

Il metodo InputMap.create() dell'SDK di input 1.0.0-beta è deprecato. Aggiorna InputMap per assegnare un identificatore di versione, disattiva completamente la funzionalità di rimappatura o assegna un elenco di chiavi riservate per il tuo gioco che non vuoi che venga utilizzato dall'utente per la rimappatura. Ogni InputMap definito utilizzando il metodo create() dell'SDK di input 1.0.0-beta è rimappabile per impostazione predefinita, è identificato con l'ID 0 e non ha chiavi prenotate.

InputMap nell'SDK di input 1.0.0-beta

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

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

InputMap nell'SDK di input 1.1.0-beta

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

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

Passaggio successivo

Continua l'upgrade alla versione 1.1.0-beta assegnando controlli diversi per scene diverse utilizzando InputContexts o aggiornando l'interfaccia utente del tuo gioco ricevendo notifiche sulla rimappatura degli eventi tramite InputRemappingListeners.

Quando aggiorni le associazioni di chiavi, dai un'occhiata alle best practice per la progettazione delle associazioni di chiavi e considera le limitazioni e le limitazioni della funzionalità di rimappatura.