Questa pagina è stata tradotta dall'API Cloud Translation.

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

Questa guida spiega come eseguire l'upgrade del tuo gioco dalla versione 1.0 all'SDK di 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 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 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 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 dell'utente per persistere durante le sessioni di gioco. Queste impostazioni vengono memorizzate localmente, pertanto 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ù PC.

Non è necessario eseguire l'upgrade dell'SDK di input per attivare la rimappatura delle chiavi nel gioco; tuttavia, questa operazione verrà 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, procedi nel seguente modo:

Esegui l'upgrade all'SDK di input 1.1.0-beta.
Aggiorna le associazioni di chiavi 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 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 come disattivata.

Puoi eseguire l'upgrade della tua versione dell'SDK di input a 1.1.0-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 set di chiavi riservate che l'utente non può rimappare e disattivare la funzionalità di rimappatura per InputAction, InputGroup o InputMap.

Quando esegui l'upgrade, prendi in considerazione le seguenti eccezioni:

Configurazioni non supportate

La rimappatura degli input è disabilitata se non vengono soddisfatte le seguenti condizioni:

Un elemento InputAction che utilizza più tasti deve essere composto da un tasto di modifica e un tasto non di modifica. Ad esempio, i tasti Maiusc + A sono validi, mentre 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 usare la stessa chiave per azioni diverse nel gioco senza conflitti. In questo modo, se un gioco utilizza uno spazio per saltare durante il gameplay e per confermare la selezione di un menu, i giocatori possono rimappare singolarmente lo spazio per accedere nei menu e lo spazio sulla 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 di input durante la rimappatura delle chiavi.

Upgrade

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'upgrade alla versione 1.1.0-beta attiva nuove funzionalità, tra cui:

Attivazione delle modifiche di contesto.
Ricezione di notifiche relative a eventi di mappatura chiave
È in corso la disattivazione della rimappatura per azione, gruppo, contesto o mappa.

Installazione

Puoi utilizzare il plug-in Unity v1.1.0-beta. Devi eliminare le eventuali versioni precedenti dell'SDK di Input installate nel gioco ed eseguire l'upgrade alla versione corrente.

Per aggiungere l'SDK di input v1.1.0-beta al tuo gioco, consulta la pagina Aggiunta dell'SDK.

Definisci campi statici

Per la versione 1.1.0-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 InputActions

Il metodo InputAction.create() dell'SDK di input 1.0.0-beta è stato ritirato. Un InputAction 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

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

InputAction nell'SDK di input 1.1.0-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 di input 1.1.0-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 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. Così come un 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:

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

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

InputGroup in Input SDK 1.1.0-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 in Input SDK 1.1.0-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 chiavi, consulta ID chiavi di monitoraggio.

Aggiorna InputMap

Il metodo InputMap.create() dell'SDK di 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 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

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

InputMap nell'SDK di input 1.1.0-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.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.