Esegui l'upgrade dell'SDK di Input per Unity alla versione 1.1

Questa guida spiega come eseguire l'upgrade del tuo gioco dall'SDK Input 1.0 all'SDK Input 1.1 per Unity. Fai clic qui per istruzioni su Java e Kotlin.

Note sulla versione

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

Per accedere a questa funzionalità, gli utenti devono aprire l'overlay, selezionare i controlli e fare clic sull'azione che vogliono 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 del rimappaggio del giocatore. Se devi conoscere il nuovo input per un'azione in-game, ad esempio la visualizzazione dei controlli della tastiera nel gioco, puoi facoltativamente registrare un callback per ricevere notifiche per gli eventi di rimappatura.

Google Play Giochi su PC archivia localmente i controlli rimappati dell'utente in modo che rimangano attivi tra le sessioni di gioco. Poiché queste impostazioni vengono memorizzate localmente, non influiscono sull'esperienza sui dispositivi mobili e vengono eliminate al momento della disinstallazione di Google Play Giochi su PC. Le impostazioni non vengono conservate su più dispositivi PC.

Non è necessario eseguire l'upgrade dell'SDK Input per abilitare il rimappaggio dei tasti nel tuo gioco, ma il rimappaggio verrà disattivato per il tuo gioco se viene rilevata una configurazione non supportata.

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

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

Se vuoi disattivare la funzionalità di rimappatura per il tuo gioco mentre continui a visualizzare 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 disattivata.

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

Quando esegui l'upgrade, tieni conto delle seguenti eccezioni:

Configurazioni non supportate

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

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

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

Introduzione a InputContext

Un InputContext consente a un gioco di utilizzare la stessa chiave per azioni diverse nel tuo gioco senza conflitti. In questo modo, se un gioco utilizza lo spazio per saltare durante il gameplay e per confermare una selezione del menu, i giocatori possono rimappare singolarmente lo spazio per accedere nei menu e da Spazio alla Freccia su durante il gameplay.

Il seguente diagramma di sequenza mostra come funziona l'API setInputContext() in fase di esecuzione:

Diagramma che mostra il flusso dell'SDK Input durante la rimappatura delle chiavi.

Esegui l'upgrade

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 di input, potresti leggere la guida all'upgrade dalla versione 0.0.4 alla versione 1.0.0-beta.

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

  • Attivazione di modifiche al contesto.
  • Ricevere notifiche di eventi di mappatura delle chiavi
  • Disattivazione della rimappatura per azione, gruppo, contesto o mappa.

Installazione

Il plug-in Unity v1.1.1-beta è disponibile per l'uso. Devi eliminare eventuali versioni precedenti dell'SDK di input installate nel tuo gioco ed eseguire l'upgrade alla versione corrente.

Per aggiungere l'SDK Input 1.1.1-beta al tuo gioco, consulta Aggiunta dell'SDK.

Definire i campi statici

Per la versione 1.1.1-beta è buona norma definire InputActions, InputGroups, InputContexts e InputMap come campi statici della classe InputMappingProvider, poiché questi campi saranno accessibili da altre parti dell'applicazione:

#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

Aggiorna le azioni di input

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

InputAction nell'SDK Input 1.0.0-beta

var driveAction = PlayInputAction.Create(
    "Drive",
    (long)InputEventIds.DRIVE,
    PlayInputControls.Create(
        new[] { AndroidKeyCode.KEYCODE_SPACE },
        new List<PlayMouseAction>()
    )
);

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

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

Per ulteriori informazioni sul controllo della versione delle associazioni di tasti, consulta Monitorare gli ID chiave.

Aggiorna i tuoi gruppi di input

Nell'SDK di input 1.1.1-beta devi identificare in modo univoco ogni InputGroup. Ogni InputAction appartiene a un InputGroup, ovvero a una raccolta di azioni correlate. In questo modo, la navigazione e la rilevabilità dei controlli durante il gameplay vengono migliorate. Proprio come un 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:

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

InputGroup nell'SDK di input 1.0.0-beta

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

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

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

Per ulteriori informazioni sul controllo della versione delle associazioni di tasti, consulta Monitorare gli ID chiave.

Aggiorna InputMap

Il metodo InputMap.create() dell'SDK Input 1.0.0-beta è stato ritirato. 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 vengano utilizzate dall'utente per la rimappatura. Ogni InputMap definito utilizzando il metodo 1.0.0-beta create() dell'SDK di input è riemappabile per impostazione predefinita, è identificato con l'ID 0 e non ha chiavi riservate.

InputMap nell'SDK Input 1.0.0-beta

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

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

Passaggio successivo

Continua l'upgrade alla versione 1.1.1 beta assegnando controlli diversi per scene diverse utilizzando InputContexts o aggiornando l'interfaccia utente del tuo gioco ricevendo una notifica sugli eventi di rimappatura utilizzando InputRemappingListeners.

Quando aggiorni le associazioni di tasti, consulta le best practice per la progettazione delle associazioni di tasti e tieni conto delle limitazioni e delle restrizioni della funzionalità di rimappatura.