Mengupgrade Input SDK untuk Unity ke versi 1.1

Panduan ini menjelaskan cara mengupgrade game Anda dari Input SDK 1.0 ke 1.1 untuk Unity. Klik di sini untuk petunjuk Java dan Kotlin.

Catatan Rilis

Google Play Game di PC mendukung pemetaan ulang kontrol keyboard berdasarkan pintasan tombol yang disediakan game menggunakan Input SDK.

Pengguna mengakses fitur ini dengan membuka overlay, memilih kontrol, lalu mengklik tindakan yang ingin mereka petakan ulang.

Google Play Game di PC memetakan setiap input yang dipetakan pengguna ke input default game Anda. Dengan cara ini, game Anda tidak perlu mengetahui pemetaan ulang pemain. Jika perlu mengetahui input baru untuk tindakan dalam game, seperti menampilkan kontrol keyboard dalam game, Anda dapat secara opsional mendaftarkan callback agar diberi tahu untuk memetakan ulang peristiwa.

Google Play Game di PC menyimpan kontrol yang dipetakan ulang setiap pengguna secara lokal sehingga tetap ada di seluruh sesi game. Karena disimpan secara lokal, setelan ini tidak memengaruhi pengalaman seluler dan akan dihapus setelah Google Play Game di PC di-uninstal. Setelan tidak dipertahankan di beberapa perangkat PC.

Anda tidak perlu mengupgrade Input SDK untuk mengaktifkan pemetaan ulang tombol dalam game, tetapi pemetaan ulang akan dinonaktifkan untuk game Anda jika konfigurasi yang tidak didukung terdeteksi.

Jika Anda ingin mengontrol pengalaman pemetaan ulang input atau fitur pemetaan ulang dinonaktifkan untuk game, ikuti langkah-langkah berikut:

Jika Anda memilih untuk tidak menggunakan fitur pemetaan ulang untuk game sambil tetap menampilkan versi hanya baca dari binding tombol, ikuti langkah-langkah berikut:

  • Upgrade ke Input SDK 1.1.0-beta.
  • Perbarui InputMap untuk menyetel fitur pemetaan ulang ke dinonaktifkan.

Anda dapat mengupgrade versi Input SDK ke 1.1.0-beta untuk memanfaatkan fitur pemetaan ulang lanjutan di Google Play Game di PC dengan menggunakan InputContexts untuk menentukan kontrol bagi berbagai scene game, menambahkan callback untuk memproses peristiwa pemetaan ulang, menentukan kumpulan tombol tetap yang tidak dapat dipetakan ulang oleh pengguna, dan menonaktifkan fitur pemetaan ulang per InputAction, InputGroup, atau InputMap.

Saat mengupgrade, pertimbangkan pengecualian berikut:

Konfigurasi yang tidak didukung

Pemetaan ulang input dinonaktifkan jika kondisi berikut tidak terpenuhi:

  • InputAction yang menggunakan beberapa tombol harus terdiri dari tombol pengubah dan non-pengubah. Misalnya, Shift + A valid, tetapi A + B, Ctrl + Alt, dan Shift + A + Tab tidak valid.

  • Dua atau beberapa objek InputAction atau InputGroup tidak dapat menggunakan ID unik yang sama.

Memperkenalkan InputContext

InputContext memungkinkan game menggunakan tombol yang sama untuk berbagai tindakan di game Anda tanpa konflik. Dengan cara ini, jika game menggunakan tombol spasi untuk melompat selama gameplay dan untuk mengonfirmasi pilihan menu, pemain dapat memetakan ulang spasi untuk enter di menu dan spasi untuk panah atas selama gameplay.

Diagram urutan berikut menunjukkan cara kerja setInputContext() API saat runtime:

Diagram yang menunjukkan alur Input SDK saat memetakan ulang tombol.

Upgrade

Game yang menggunakan implementasi Input SDK sebelumnya masih mendukung pemetaan ulang dasar, kecuali jika menggunakan konfigurasi yang tidak didukung. Jika game Anda menggunakan SDK Input versi sebelumnya, pertimbangkan untuk membaca panduan upgrade dari 0.0.4 ke 1.0.0-beta.

Upgrade ke versi 1.1.0-beta akan mengaktifkan fitur baru, termasuk:

  • Memicu perubahan konteks.
  • Menerima notifikasi peristiwa konfigurasi tombol.
  • Menonaktifkan pemetaan ulang per Tindakan, Grup, Konteks, atau Peta.

Penginstalan

Plugin Unity v1.1.0-beta tersedia untuk Anda gunakan. Anda harus menghapus Input SDK versi sebelumnya yang diinstal di game dan mengupgrade ke versi saat ini.

Untuk menambahkan Input SDK v1.1.0-beta ke game, lihat Menambahkan SDK.

Menentukan kolom statis

Untuk versi 1.1.0-beta, sebaiknya tentukan InputActions, InputGroups, InputContexts, dan InputMap sebagai kolom statis class InputMappingProvider, karena kolom ini akan dapat diakses dari bagian lain aplikasi Anda:

#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

Mengupdate InputActions

Metode InputAction.create() Input SDK 1.0.0-beta tidak digunakan lagi. InputAction memiliki ID versi dan dapat ditandai sebagai dapat dipetakan ulang atau tidak. InputAction yang ditentukan menggunakan metode create() Input SDK 1.0.0-beta dapat dipetakan ulang secara default dan tidak memiliki informasi pembuatan versi:

InputAction di Input SDK 1.0.0-beta

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

InputAction di Input SDK 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 di Input SDK 1.1.0-beta (dengan string versi)

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

Untuk mengetahui informasi selengkapnya tentang pembuatan versi pintasan tombol, lihat Melacak ID tombol.

Mengupdate InputGroups

Dalam Input SDK 1.1.0-beta, Anda harus mengidentifikasi setiap InputGroup secara unik. Setiap InputAction adalah milik InputGroup -- kumpulan tindakan terkait. Hal ini meningkatkan navigasi dan visibilitas kontrol selama gameplay. Sama seperti InputAction harus memiliki ID unik di antara semua tindakan dalam satu InputContext, InputGroup harus memiliki ID unik di seluruh grup yang sudah ada.

Untuk contoh di bagian ini, game memiliki dua objek InputContext yang mewakili menu dan gameplay utama. ID yang sesuai dilacak untuk setiap InputGroup dalam konteks ini menggunakan enumerasi berikut:

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
}

Seperti InputAction, metode InputGroup.create() Input SDK 1.0.0-beta tidak digunakan lagi. Anda harus mengupdate InputGroup di game dengan ID versi dan boolean yang menunjukkan apakah objek InputAction dalam grup Anda dapat dipetakan ulang. Grup yang dibuat dengan metode create() Input SDK 1.0.0-beta yang tidak digunakan lagi dapat dipetakan ulang, memiliki ID 0, dan ID versinya adalah string kosong (""):

InputGroup di Input SDK 1.0.0-beta

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

InputGroup di 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 di Input SDK 1.1.0-beta (dengan string versi)

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

Untuk mengetahui informasi selengkapnya tentang pembuatan versi pintasan tombol, lihat Melacak ID tombol.

Mengupdate InputMap

Metode InputMap.create() Input SDK 1.0.0-beta tidak digunakan lagi. Update InputMap Anda untuk menetapkan ID versi, memilih tidak ikut sepenuhnya dari fitur pemetaan ulang, atau menetapkan daftar kunci yang ditetapkan untuk game Anda yang tidak ingin digunakan untuk pemetaan ulang oleh pengguna. Setiap InputMap yang ditentukan menggunakan metode create() Input SDK 1.0.0-beta dapat dipetakan ulang secara default, diidentifikasi dengan ID 0, dan tidak memiliki tombol yang ditetapkan.

InputMap di Input SDK 1.0.0-beta

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

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

Langkah berikutnya

Lanjutkan upgrade ke versi 1.1.0-beta dengan Menetapkan kontrol yang berbeda untuk scene yang berbeda menggunakan InputContexts atau mengupdate UI game dengan Mendapatkan notifikasi peristiwa pemetaan ulang menggunakan InputRemappingListeners.

Saat memperbarui pintasan tombol, lihat Praktik terbaik untuk mendesain pintasan tombol serta pertimbangkan batasan dan pembatasan fitur pemetaan ulang.