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

Questa guida spiega come eseguire l'upgrade del gioco dalla versione 1.0 alla versione 1.1 dell'SDK Input per Unity. Fai clic qui per istruzioni su Java e Kotlin.

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 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 i controlli rimappati dell'utente localmente per mantenerli tra le sessioni di gioco. Poiché queste impostazioni vengono memorizzate localmente, non influiscono sull'esperienza mobile e vengono eliminate al momento della disinstallazione di Google Play Giochi su PC. Le impostazioni 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 verrà disattivata per il 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 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 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.

Quando esegui l'upgrade, tieni presente le seguenti eccezioni:

Configurazioni non supportate

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

  • Una InputAction che utilizza più tasti deve essere composta 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 sono validi.

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

Introduzione di InputContext

Un InputContext consente a un gioco di utilizzare lo stesso tasto per azioni diverse nel 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 individualmente Spazio su Invio nei menu e Spazio su Freccia su durante il gameplay.

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

Diagramma che mostra il flusso dell'SDK Input durante la rimappatura dei tasti.

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 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:

  • Attivazione di modifiche del contesto.
  • Ricezione di notifiche relative agli eventi di mappatura dei tasti
  • Disattivazione della rimappatura per azione, gruppo, contesto o mappa.

Installazione

Il plug-in Unity v1.1.1-beta è disponibile per l'uso. Devi eliminare tutte le versioni precedenti dell'SDK Input installate nel gioco ed eseguire l'upgrade alla versione attuale.

Per aggiungere l'SDK Input v1.1.1-beta al tuo gioco, vedi Aggiungere l'SDK.

Definisci i campi statici

Per la versione 1.1.1-beta è consigliabile definire InputActions, InputGroups, InputContexts e InputMap come campi statici della classe InputMappingProvider, in quanto 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

Aggiornare InputActions

Il metodo InputAction.create() dell'SDK Input 1.0.0-beta è obsoleto. Un InputAction 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

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 in Input SDK 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 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. 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 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

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

InputGroup nell'SDK 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 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 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 è stato ritirato. 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

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

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

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.