Mengupgrade Input SDK untuk Java dan Kotlin ke versi 1.1

Panduan ini menjelaskan cara mengupgrade game dari Input SDK 1.0.0-beta untuk Java dan Kotlin ke 1.1.0-beta. Lihat panduan upgrade Unity untuk mengetahui petunjuk khusus Unity.

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, hal ini tidak memengaruhi pengalaman seluler dan dihapus setelah uninstal Google Play Game di PC. Setelan kontrol tidak dipertahankan di beberapa perangkat PC.

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

Jika Anda ingin mengontrol pengalaman pemetaan ulang input, atau jika fitur pemetaan ulang dinonaktifkan untuk game, lakukan langkah-langkah berikut untuk me-resolve:

• Upgrade ke Input SDK 1.1.0-beta.
• Perbarui binding tombol apa pun untuk menghindari konfigurasi yang tidak didukung.
• Perbarui InputMap untuk menyetel fitur pemetaan ulang ke diaktifkan.

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.

Pertimbangkan pengecualian berikut saat mengupgrade ke versi SDK baru:

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.

Upgrade

Input SDK 1.1.0-beta kompatibel dengan Input SDK 1.0.0-beta. Game yang menggunakan implementasi Input SDK 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 kontrol scene.
• Menerima notifikasi peristiwa konfigurasi tombol.
• Menonaktifkan pemetaan ulang per Tindakan, Grup, Konteks, atau Peta.

Mengupgrade dependensi

Jika Anda menggunakan Gradle untuk mengimpor Input SDK, upgrade ke versi terbaru:

// build.gradle
dependencies {
   ...
   implementation 'com.google.android.libraries.play.games:inputmapping:1.1.0-beta'
   ...
}

Menentukan kolom statis

Untuk versi 1.1.0-beta, sebaiknya tentukan objek InputAction, InputGroup, InputContext, dan InputMap sebagai kolom statis dari class InputMappingProvider karena kolom ini dapat diakses dari bagian lain aplikasi Anda:

class InputSDKProvider : InputMappingProvider {
    override fun onProvideInputMap(): InputMap { return gameInputMap }

    companion object {
        const val INPUTMAP_VERSION = "1.0.0"

        private val moveUpInputAction = InputAction.create(...)
        private val movementInputGroup = InputGroup.create(...)
        val menuContext = InputContext.create(...)
        val gameInputMap = InputMap.create(...)
    }
}

public class MyInputMappingProvider implements InputMappingProvider {
    private static final String INPUTMAP_VERSION = "1.0.0";

    private static final InputAction moveUpInputAction =
        InputAction.create(...);
    private static final InputGroup movementInputGroup = InputGroup.create(...);
    public static final InputContext menuContext = InputContext.create(...);
    public static final InputMap gameInputMap = InputMap.create(...);

    @Override
    public InputMap onProvideInputMap() {
        return gameInputMap;
    }
}

Mengupdate InputActions

Metode InputAction.create() Input SDK 1.0.0-beta tidak digunakan lagi. InputAction kini 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

val jumpInputAction = InputAction.create(
    "Jump",
    InputEventIds.JUMP.id,
    InputControls.create(
        listOf(KeyEvent.KEYCODE_SPACE),
        emptyList()
    )
)

InputAction moveUpInputAction = InputAction.create(
    "Move Up",
    InputEventIds.MOVE_UP.ordinal(),
    InputControls.create(
        Collections.singletonList(KeyEvent.KEYCODE_W),
        Collections.emptyList()
    )
);

InputAction di Input SDK 1.1.0-beta

companion object {
  private val moveUpInputAction = InputAction.create(
    "Move Up",
    InputActionsIds.DRIVE.ordinal.toLong(),
    InputControls.create(listOf(KeyEvent.KEYCODE_W), emptyList()),
    InputEnums.REMAP_OPTION_ENABLED) // This action is remappable
}

private static final InputAction moveUpInputAction = InputAction.create(
    "Move Up",
    InputEventIds.MOVE_UP.ordinal(),
    InputControls.create(
            Collections.singletonList(KeyEvent.KEYCODE_W),
            Collections.emptyList()),
    InputEnums.REMAP_OPTION_ENABLED // this action is remappable
);

InputAction di Input SDK 1.1.0-beta (dengan string versi)

private val enterMenuInputAction = InputAction.create(
    "Enter menu",
    InputControls.create(listOf(KeyEvent.KEYCODE_ENTER), emptyList()),
    InputIdentifier.create(
    INPUTMAP_VERSION, InputActionsIds.ENTER_MENU.ordinal.toLong()),
    InputEnums.REMAP_OPTION_ENABLED
)

private static final InputAction moveUpInputAction = InputAction.create(
    "Move Up",
    InputControls.create(
            Collections.singletonList(KeyEvent.KEYCODE_W),
            Collections.emptyList()),
    InputIdentifier.create(
            INPUTMAP_VERSION,
            InputEventIds.MOVE_UP.ordinal()),
    InputEnums.REMAP_OPTION_ENABLED // this action is remappable
);

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. Dengan cara yang 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:

enum class 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
}

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

val movementInputGroup = InputGroup.create(
    "Basic Movement",
    listOf(
        moveUpInputAction,
        moveLeftInputAction,
        moveDownInputAction,
        moveRightInputAction,
        jumpInputAction,
        runInputAction)
)

InputGroup movementInputGroup = InputGroup.create(
    "Basic movement",
    Arrays.asList(
        moveUpInputAction,
        moveLeftInputAction,
        moveDownInputAction,
        moveRightInputAction,
        jumpInputAction,
        runInputAction
    )
);

InputGroup di Input SDK 1.1.0-beta

companion object {
    private val movementInputGroup = InputGroup.create(
        "Basic movement",
        listOf(
            moveUpInputAction,
            moveLeftInputAction,
            moveDownInputAction,
            moveRightInputAction,
            jumpInputAction,
            runInputAction),
        InputGroupsIds.BASIC_MOVEMENT.ordinal.toLong(),
        // All the actions in this groups can't be remapped
        InputEnums.REMAP_OPTION_DISABLED
    )
}

private static final InputGroup movementInputGroup = InputGroup.create(
    "Basic movement",
    Arrays.asList(
            moveUpInputAction,
            moveLeftInputAction,
            moveDownInputAction,
            moveRightInputAction,
            jumpInputAction,
            runInputAction
    ),
    InputGroupsIds.BASIC_MOVEMENT.ordinal(),
    // All the actions in this groups can't be remapped
    InputEnums.REMAP_OPTION_DISABLED
);

InputGroup di Input SDK 1.1.0-beta (dengan string versi)

companion object {
    private val movementInputGroup  = InputGroup.create(
        "Basic movement",
        listOf(
            moveUpInputAction,
            moveLeftInputAction,
            moveDownInputAction,
            moveRightInputAction,
            jumpInputAction,
            runInputAction),
        InputIdentifier.create(
            INPUTMAP_VERSION, InputGroupsIds.BASIC_MOVEMENT.ordinal.toLong()),
        // All the actions in this groups can't be remapped
        InputEnums.REMAP_OPTION_DISABLED
    )
}

private static final InputGroup movementInputGroup = InputGroup.create(
    "Basic movement",
    Arrays.asList(
            moveUpInputAction,
            moveLeftInputAction,
            moveDownInputAction,
            moveRightInputAction,
            jumpInputAction,
            runInputAction
    ),
    InputIdentifier.create(
            INPUTMAP_VERSION,
            InputGroupsIds.BASIC_MOVEMENT.ordinal()),
    // All the actions in this groups can't be remapped
    InputEnums.REMAP_OPTION_DISABLED
);

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

val gameInputMap = InputMap.create(
    listOf(movementInputGroup, mouseMovementInputGroup),
    MouseSettings.create(true, false)
)

InputMap gameInputMap = InputMap.create(
    Arrays.asList(movementInputGroup, mouseMovementInputGroup),
    MouseSettings.create(true, false)
);

InputMap di Input SDK 1.1.0-beta

companion object {

  const val INPUTMAP_VERSION = "1.0.0"
  const val INPUT_MAP_ID = 0

  val gameInputMap = InputMap.create(
    listOf(movementInputGroup, mouseMovementInputGroup),
    MouseSettings.create(true, false),
    InputIdentifier.create(INPUTMAP_VERSION, INPUT_MAP_ID.toLong()),
    InputEnums.REMAP_OPTION_ENABLED,
    // Use ESCAPE as reserved key
    listof(InputControls.create(listOf(KeyEvent.KEYCODE_ESCAPE), emptyList()))
  )
}

public static final String INPUT_MAP_VERSION = "1.0.0-beta";
public static final long INPUT_MAP_ID = 0;

public static final InputMap gameInputMap = InputMap.create(
        Arrays.asList(movementInputGroup, mouseMovementInputGroup),
        MouseSettings.create(true, false),
        InputIdentifier.create(INPUTMAP_VERSION, INPUT_MAP_ID),
        InputEnums.REMAP_OPTION_ENABLED,
        // Use ESC key as reserved key
        Arrays.asList(
                InputControls.create(
                        Collections.singletonList(KeyEvent.KEYCODE_ESCAPE),
                        Collections.emptyList()
                )
        )
);

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.