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 le istruzioni per Java e Kotlin.

Note di rilascio

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

Gli utenti accedono a questa funzionalità aprendo la sovrapposizione, selezionando controlli, e poi facendo 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 della rimappatura del giocatore. Se devi conoscere il nuovo input per un'azione in-game, ad esempio per visualizzare i controlli della tastiera nel gioco, puoi facoltativamente registrare un callback per ricevere una notifica per gli eventi di rimappatura.

Google Play Games su PC memorizza i controlli rimappati dall'utente localmente per mantenerli tra le sessioni di gioco. Poiché queste impostazioni vengono memorizzate localmente, non influenzano l'esperienza mobile e vengono eliminate al momento della disinstallazione di Google Play Giochi su PC. Le impostazioni non vengono mantenute su più PC.

Non è necessario eseguire l'upgrade dell'SDK Input per attivare 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 degli input o se la funzionalità di rimappatura è disattivata per il 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 gioco, ma continuare 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 InputMap per impostare la funzionalità di rimappatura su disattivata.

Puoi eseguire l'upgrade della versione dell'SDK Input a 1.1.1-beta per sfruttare le funzionalità di rimappatura avanzate in Google Play Giochi su PC utilizzando InputContexts per definire i controlli per le diverse scene del gioco, aggiungere callback per ascoltare gli eventi di rimappatura, definire un insieme di tasti riservati che 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 vengono 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 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 lo stesso tasto per diverse azioni 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 lo spazio per accedere ai menu e lo spazio per la 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 versione 1.0.0-beta.

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

  • Attivazione delle modifiche del contesto.
  • Ricezione di notifiche degli 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 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 gioco, consulta Aggiungere l'SDK.

Definisci i campi statici

Per la versione 1.1.1-beta, è consigliabile definire i tuoi 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 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 create() dell'SDK Input 1.0.0-beta è 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 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 delle versioni delle associazioni di tasti, consulta Monitorare gli ID tasto.

Aggiorna InputGroups

Nell'SDK Input 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 rilevabilità 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, anche il metodo InputGroup.create() dell'SDK Input 1.0.0-beta è obsoleto. 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 create() dell'SDK Input obsoleto 1.0.0-beta 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 ulteriori informazioni sul controllo delle versioni delle associazioni di tasti, consulta Monitorare gli ID tasto.

Aggiorna InputMap

Il metodo InputMap.create() dell'SDK Input 1.0.0-beta è obsoleto. Aggiorna InputMap per assegnare un identificatore di versione, disattivare completamente la funzionalità di rimappatura o assegnare un elenco di tasti riservati per il gioco che non vuoi che l'utente utilizzi per la rimappatura. 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 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()
);

Passaggi successivi

Continua l'upgrade alla versione 1.1.1-beta assegnando controlli diversi per scene diverse utilizzando InputContexts o aggiornando l'interfaccia utente del 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 presente le restrizioni e le limitazioni della funzionalità di rimappatura.