Google Play Game masih dalam versi beta terbuka.

Memulai Input SDK

Topik ini menjelaskan cara menyiapkan dan menampilkan overlay Input SDK dalam game yang mendukung Google Play Game. Tugas-tugas termasuk menambahkan SDK ke game dan membuat peta input, yang berisi tindakan game untuk penetapan input pengguna. Untuk game yang mendukung perubahan binding tombol, Anda juga harus melacak dan menyinkronkan perubahan dengan SDK.

Sebelum memulai

Sebelum menambahkan Input SDK ke game, Anda harus menambahkan dukungan keyboard dan mouse.

Menambahkan SDK

Input SDK belum tersedia untuk didownload. Library ini akan tersedia sebagai dependensi maven untuk project Java dan Kotlin serta unitypackage dan tgz untuk developer Unity.

Ingatlah untuk menyatakan minat agar menjadi salah satu yang pertama mengakses SDK baru.

Membuat pemetaan input

Pemetaan input mewakili tindakan game ke tugas input pengguna untuk ditampilkan dalam overlay Input SDK. Untuk menghasilkan pemetaan input, Anda harus mem-build InputMap, lalu menampilkannya dengan InputMappingProvider.

Berikut adalah contoh outline InputMappingProvider:

Kotlin

class MyInputMapProvider : InputMappingProvider() {
    override fun onProvideInputMap(): InputMap {
        TODO("Not yet implemented")
    }
}

Java

public class MyInputMapProvider extends InputMappingProvider {
    @NonNull
    @Override
    public InputMap onProvideInputMap() {
        // TODO: return an InputMap
    }
}

C#

private class MyInputMappingProvider : InputMappingProvider
{
    public InputMap OnProvideInputMap()
    {
        // TODO("Not yet implemented")
    }
}

Bagian berikutnya menjelaskan cara membuat InputMap untuk ditampilkan dari InputMappingProvider.

Menentukan tindakan input

Class InputAction digunakan untuk memetakan kombinasi tombol atau tombol ke tindakan game.

Contoh ini memetakan tombol spasi ke tindakan melompat:

Kotlin

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

Java

InputAction jumpInputAction = InputAction.create(
        "Jump",
        InputEventIds.JUMP.ordinal(),
        InputControls.create(
                Collections.singletonList(KeyEvent.KEYCODE_SPACE),
                Collections.emptyList()
        )
);

C#

var jumpInputAction = new InputAction
{
    ActionLabel = "Jump",
    UniqueId = (int)InputEventIds.Jump,
    InputControls = new InputControls
    {
        AndroidKeycodes = new[]
        {
            AndroidKeyCode.KEYCODE_SPACE
        }
    }
};

Screenshot overlay input yang menunjukkan tindakan melompat terikat ke
tombol Spasi.

Tindakan juga dapat mewakili input mouse. Contoh ini menetapkan klik kanan ke tindakan pemindahan:

Kotlin

val cmbMove = InputAction.create(
    "Move",
    InputEventIds.CMB_MOVE.id,
    InputControls.create(
        emptyList(),
        listOf(InputControls.MOUSE_RIGHT_CLICK)
    )
)

Java

InputAction cmbMove = InputAction.create(
        "Move",
        InputEventIds.CMB_MOVE.ordinal(),
        InputControls.create(
                Collections.emptyList(),
                Collections.singletonList(InputControls.MOUSE_RIGHT_CLICK)
        )
);

C#

var cmbMove = new InputAction
{
    ActionLabel = "Move",
    UniqueId = (int)InputEventIds.CmbMove,
    InputControls = new InputControls
    {
        MouseActions = new[]
        {
            MouseAction.MouseRightClick
        }
    }
};

Screenshot overlay input tempat tindakan pemindahan terikat dengan
klik kanan.

Kombinasi tombol ditentukan dengan meneruskan beberapa kode tombol ke InputAction. Dalam contoh ini, Spasi+Shift dipetakan ke tindakan berlari, yang berfungsi bahkan saat tombol Spasi dipetakan untuk melompat.

Kotlin

val cmbDash = InputAction.create(
    "Dash",
    InputEventIds.CMB_DASH.id,
    InputControls.create(
        listOf(KeyEvent.KEYCODE_SPACE, KeyEvent.KEYCODE_SHIFT_LEFT),
        emptyList()
    )
)

Java

InputAction cmbDash = InputAction.create(
        "Dash",
        InputEventIds.CMB_DASH.ordinal(),
        InputControls.create(
                Arrays.asList(KeyEvent.KEYCODE_SHIFT_LEFT, KeyEvent.KEYCODE_SPACE),
                Collections.emptyList()
        )
);

C#

var cmbDash = new InputAction
{
    ActionLabel = "Dash",
    UniqueId = (int)InputEventIds.CmbDash,
    InputControls = new InputControls
    {
        AndroidKeycodes = new[]
        {
            AndroidKeyCode.KEYCODE_SPACE, AndroidKeyCode.KEYCODE_SHIFT_LEFT
        }
    }
};

Screenshot dari overlay input tempat Shift+Spasi terikat ke
tindakan berlari.

Dengan Input SDK, Anda dapat mencampur mouse dan tombol kunci secara bersamaan untuk satu perintah. Contoh ini menunjukkan ketika tombol shift dan klik kanan ditekan secara bersamaan akan menambahkan titik jalan dalam game ini:

Kotlin

val cmbWaypoint = InputAction.create(
    "Add Waypoint",
    InputEventIds.CMB_WAYPOINT.id,
    InputControls.create(
        listOf(KeyEvent.KEYCODE_SHIFT_LEFT),
        listOf(InputControls.MOUSE_RIGHT_CLICK)
    )
)

Java

InputAction cmbWaypoint = InputAction.create(
        "Add Waypoint",
        InputEventIds.CMB_WAYPOINT.ordinal(),
        InputControls.create(
                Collections.singletonList(KeyEvent.KEYCODE_SHIFT_LEFT),
                Collections.singletonList(InputControls.MOUSE_RIGHT_CLICK)
        )
);

C#

var cmbWaypoint = new InputAction
{
    ActionLabel = "Add Waypoint",
    UniqueId = (int)InputEventIds.CmbWaypoint,
    InputControls = new InputControls
    {
        AndroidKeycodes = new[]
        {
            AndroidKeyCode.KEYCODE_SHIFT_LEFT
        },
        MouseActions = new[]
        {
            MouseAction.MouseRightClick
        }
    }
};

Screenshot overlay input tempat tindakan Add Waypoint terikat ke
tombol Shift+klik kanan.

Bagian ini menjelaskan panggilan metode dalam contoh kode:

Kotlin

InputAction.create memiliki parameter berikut:

  • actionLabel adalah string yang ditampilkan di UI untuk mewakili tindakan ini. Pelokalan tidak dilakukan untuk Anda, jadi Anda bebas melakukan pelokalan apa pun di awal.
  • uniqueId adalah ID bilangan bulat untuk mengidentifikasi tindakan ini. Setiap tindakan harus memiliki ID unik yang konsisten, sehingga enumerasi digunakan dalam contoh ini. Lihat Pelacakan ID Kunci untuk informasi selengkapnya.
  • inputControls menentukan kontrol input yang digunakan pada tindakan. Ini akan dipetakan ke glyph yang konsisten di antarmuka pengguna.

InputControls.create membuat input yang terkait dengan tindakan. Parameternya adalah:

  • keycodes adalah daftar bilangan bulat yang mewakili input keyboard yang terkait dengan suatu tindakan. Ini didefinisikan dalam class KeyEvent.
  • mouseActions adalah daftar bilangan bulat yang mewakili input mouse yang terkait dengan tindakan. Ini ditentukan dalam InputControls itu sendiri.

Java

InputAction.create memiliki parameter berikut:

  • actionLabel adalah string yang ditampilkan di UI untuk mewakili tindakan ini. Pelokalan tidak dilakukan untuk Anda, jadi Anda bebas melakukan pelokalan apa pun di awal.
  • uniqueId adalah ID bilangan bulat untuk mengidentifikasi tindakan ini. Setiap tindakan harus memiliki ID unik yang konsisten, sehingga enumerasi digunakan dalam contoh ini. Lihat Pelacakan ID Kunci untuk informasi selengkapnya.
  • inputControls menentukan kontrol input yang digunakan pada tindakan. Ini akan dipetakan ke glyph yang konsisten di antarmuka pengguna.

InputControls.create membuat input yang terkait dengan tindakan. Parameternya adalah:

  • keycodes adalah daftar bilangan bulat yang mewakili input keyboard yang terkait dengan suatu tindakan. Ini didefinisikan dalam class KeyEvent.
  • mouseActions adalah daftar bilangan bulat yang mewakili input mouse yang terkait dengan tindakan ini. Ini ditentukan dalam InputControls itu sendiri.

C#

InputAction memiliki kolom berikut:

  • ActionLabel adalah string yang ditampilkan di UI untuk mewakili tindakan ini. Pelokalan tidak dilakukan untuk Anda, jadi Anda bebas melakukan pelokalan apa pun di awal.
  • UniqueId adalah ID bilangan bulat untuk mengidentifikasi tindakan ini. Setiap tindakan harus memiliki ID unik yang konsisten sehingga enum digunakan dalam contoh ini. Lihat Melacak ID Tombol.
  • InputControls menentukan kontrol input yang digunakan tindakan ini. Ini akan dipetakan ke glyph yang konsisten di antarmuka pengguna.

InputControls mewakili input yang terkait dengan tindakan. yang memiliki kolom berikut:

  • AndroidKeycodes adalah daftar bilangan bulat yang mewakili input keyboard yang terkait dengan suatu tindakan. Ini didefinisikan dalam class AndroidKeycode.
  • MouseActions adalah daftar nilai MouseAction yang mewakili input mouse yang terkait dengan tindakan ini.

Menentukan grup input

InputGroup adalah grup objek InputAction yang serupa. Contoh:

  • Anda dapat menentukan kumpulan input yang berbeda untuk mengakses menu vs bergerak dalam game.
  • Anda dapat menentukan kumpulan input yang berbeda, bergantung pada mode gerakan dalam game, seperti mengemudi vs berjalan.
  • Anda dapat menentukan kumpulan input yang berbeda berdasarkan status game saat ini, seperti membuka dunia dalam game vs memainkan tokoh game dalam level individu.

Dengan mengatur input Anda ke dalam grup, Anda memudahkan pemain untuk menemukan binding tombol yang tepat untuk situasi mereka saat ini.

Kotlin

val movementInputGroup = InputGroup.create(
    "Basic Movement",
    listOf(jumpInputAction, leftInputAction, rightInputAction, useInputAction)
)

Java

InputGroup movementInputGroup = InputGroup.create(
        "Basic Movement",
        Arrays.asList(jumpInputAction, leftInputAction, rightInputAction, useInputAction)
);

C#

var movementInputGroup = new InputGroup
{
    GroupLabel = "Basic Movement",
    InputActions = new List<InputAction>
    {
        jumpInputAction,
        leftInputAction,
        rightInputAction,
        useInputAction
    }
}

Bagian ini menjelaskan panggilan metode yang digunakan dalam contoh kode:

Kotlin

InputGroup.create memiliki parameter berikut:

  • groupLabel adalah string yang akan ditampilkan di UI, yang dapat digunakan untuk mengelompokkan kumpulan tindakan secara logis. String ini tidak dilokalkan untuk Anda.
  • inputActions adalah daftar objek InputAction yang Anda tentukan dalam langkah terakhir. Semua tindakan tersebut akan ditampilkan secara visual di bawah judul grup ini.

Java

InputGroup.create memiliki parameter berikut:

  • groupLabel adalah string yang akan ditampilkan di UI, yang dapat digunakan untuk mengelompokkan kumpulan tindakan secara logis. String ini tidak dilokalkan untuk Anda.
  • inputActions adalah daftar objek InputAction yang Anda tentukan dalam langkah terakhir. Semua tindakan tersebut akan ditampilkan secara visual di bawah judul grup ini.

C#

InputGroup memiliki kolom berikut:

  • GroupLabel adalah string yang akan ditampilkan di UI, yang dapat digunakan untuk mengelompokkan kumpulan tindakan secara logis. String ini tidak dilokalkan untuk Anda.
  • InputActions adalah daftar objek InputAction yang Anda tentukan dalam langkah terakhir. Semua tindakan tersebut akan ditampilkan secara visual di bawah judul grup ini.

Mem-build peta input

InputMap adalah kumpulan semua objek InputGroup yang tersedia dalam sebuah game, dan karena itu semua objek InputAction dapat diharapkan untuk dijalankan.

Dalam contoh berikut, objek MovementInputGroup dikelompokkan dengan objek MouseSettings. Objek MouseSettings menunjukkan bahwa sensitivitas mouse dapat disesuaikan dan bahwa mouse terbalik pada sumbu y:

Kotlin

return InputMap.create(
    listOf(movementInputGroup, specialInputGroup),
    MouseSettings.create(true, true)
)

Java

return InputMap.create(
        Arrays.asList(movementInputGroup, specialInputGroup),
        MouseSettings.create(true, true)
);

C#

return new InputMap
{
    InputGroups = new List<InputGroup> {movementInputGroup, specialInputGroup},
    MouseSettings = new MouseSettings
    {
        AllowMouseSensitivityAdjustment = true,
        InvertMouseMovement = true
    }
}

Mengirimkan peta input

Setelah InputMapProvider ditulis untuk game yang menampilkan InputMap yang valid, game harus terdaftar dengan Input SDK. Jika input game tidak pernah berubah, ini hanya perlu dilakukan satu kali selama masa aktif game karena InputMapProvider tidak terpengaruh oleh peristiwa siklus proses Android.

Kotlin

private val myInputMapProvider by lazy {
    MyInputMapProvider()
}

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    val inputMappingClient = Input.getInputMappingClient(this)
    inputMappingClient.registerInputMappingProvider(myInputMapProvider)
}

Java

private final MyInputMapProvider myInputMapProvider = new MyInputMapProvider();

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    InputMappingClient inputMappingClient = Input.getInputMappingClient(this);
    inputMappingClient.registerInputMappingProvider(myInputMapProvider);
}

C#

public void Start() {
    InputMappingClient inputMappingClient = Input.GetInputMappingClient();
    inputMappingClient.registerInputMappingProvider(myInputMapProvider);
}

Anda harus membatalkan pendaftaran penyedia pemetaan input setelah game selesai, meskipun SDK cukup cerdas untuk menghindari kebocoran resource jika Anda tidak melakukannya.

Kotlin

override fun onDestroy() {
    val inputMappingClient = Input.getInputMappingClient(this)
    inputMappingClient.unregisterInputMappingProvider(myInputMapProvider)

    super.onDestroy()
}

Java

@Override
protected void onDestroy() {
    InputMappingClient inputMappingClient = Input.getInputMappingClient(this);
    inputMappingClient.unregisterInputMappingProvider(myInputMapProvider);

    super.onDestroy();
}

C#

public void OnDestroy() {
    InputMappingClient inputMappingClient = Input.GetInputMappingClient();
    inputMappingClient.unregisterInputMappingProvider(myInputMapProvider);
}

Melacak ID kunci

Anda harus melacak ID unik untuk setiap InputAction yang Anda tentukan. Penghitungan berikut melacak ID unik untuk semua sampel dalam topik ini. Karena ID digunakan untuk melacak perubahan kunci, jangan gunakan hash dari nama tindakan yang dilokalkan.

Kotlin

enum class InputEventIds(val id: Int) {
    JUMP(0),
    LEFT(1),
    RIGHT(2),
    USE(3),
    SPECIAL_JUMP(4),
    SPECIAL_DUCK(5),
}

Java

public enum InputEventIds {
    JUMP,
    LEFT,
    RIGHT,
    USE,
    SPECIAL_JUMP,
    SPECIAL_DUCK
}

C#

public enum InputEventIds
{
    JUMP,
    LEFT,
    RIGHT,
    USE,
    SPECIAL_JUMP,
    SPECIAL_DUCK
}

Uji

Ada dua cara untuk menguji apakah Input SDK telah diterapkan dengan benar. Cukup dengan membukanya di UI Google Play Game untuk melihat apa yang mungkin dilihat pemain atau dalam adb shell untuk pengujian dan verifikasi otomatis.

Antarmuka pengguna

Untuk menguji di UI Google Play Game, tekan Shift+Tab untuk membuka Dasbor Game. Dari dasbor, klik Controls untuk melihat daftar kontrol yang saat ini terikat.

Gambar yang mengilustrasikan alur yang dijelaskan di atas. Shift+Tab akan membuka Dasbor Game. Selanjutnya, mengklik &quot;Controls&quot; akan membuka overlay kontrol. Overlay ini menampilkan grup yang disebut &quot;Basic Movement&quot; dengan &quot;Jump&quot;, &quot;Left&quot;, dan &quot;Right&quot; di dalamnya. Setiap kontrol menampilkan kontrol yang melakukan tindakan tersebut. Misalnya: &quot;Jump&quot; bertuliskan &quot;Key W + Key Up&quot; di bawahnya, lalu di sebelah kanannya ada gambar besar tombol bertuliskan &quot;w&quot; dan tombol bertuliskan &quot;up&quot;. Ada juga bagian bernama &quot;Special Input&quot; yang mencantumkan &quot;Duck&quot;.

Command line

Input juga dapat diverifikasi melalui adb pada command line, yang dapat membantu pengujian fitur secara otomatis.

Untuk mendapatkan peta input saat ini, gunakan perintah adb shell berikut (ganti MY.PACKAGE.NAME dengan nama game Anda):

adb shell dumpsys input_mapping_service --get MY.PACKAGE.NAME

Anda akan melihat output yang serupa dengan ini jika berhasil mendaftarkan InputMap:

Getting input map for com.example.inputsample...
Successfully received the following inputmap:
# com.google.android.libraries.play.games.InputMap@d73526e1
input_groups {
  group_label: "Basic Movement"
  input_actions {
    action_label: "Jump"
    input_controls {
      keycodes: 51
      keycodes: 19
    }
    unique_id: 0
  }
  input_actions {
    action_label: "Left"
    input_controls {
      keycodes: 29
      keycodes: 21
    }
    unique_id: 1
  }
  input_actions {
    action_label: "Right"
    input_controls {
      keycodes: 32
      keycodes: 22
    }
    unique_id: 2
  }
  input_actions {
    action_label: "Use"
    input_controls {
      keycodes: 33
      keycodes: 66
      mouse_actions: MOUSE_LEFT_CLICK
      mouse_actions_value: 0
    }
    unique_id: 3
  }
}
input_groups {
  group_label: "Special Input"
  input_actions {
    action_label: "Jump"
    input_controls {
      keycodes: 51
      keycodes: 19
      keycodes: 62
      mouse_actions: MOUSE_LEFT_CLICK
      mouse_actions_value: 0
    }
    unique_id: 4
  }
  input_actions {
    action_label: "Duck"
    input_controls {
      keycodes: 47
      keycodes: 20
      keycodes: 113
      mouse_actions: MOUSE_RIGHT_CLICK
      mouse_actions_value: 1
    }
    unique_id: 5
  }
}
mouse_settings {
  allow_mouse_sensitivity_adjustment: true
  invert_mouse_movement: true
}

Menyinkronkan perubahan binding tombol

Banyak game yang memungkinkan pemain menyesuaikan binding tombol. Oleh karena itu, Anda harus memastikan bahwa data yang ditampilkan dalam InputMapProvider sudah yang terbaru untuk setelan pemain saat ini. Jika perlu, Anda dapat memanggil registerInputMappingProvider dengan aman menggunakan peta input terbaru setiap kali pemain selesai mengubah skema input mereka.

Pelokalan

Input SDK tidak menggunakan sistem pelokalan Android. Akibatnya, Anda harus menyediakan string yang dilokalkan saat mengirimkan InputMap. Namun, ini juga memungkinkan Anda menggunakan sistem pelokalan game engine.

Langkah berikutnya

Setelah mengintegrasikan Input SDK ke dalam game, Anda dapat melanjutkan persyaratan Google Play Game lainnya. Untuk informasi selengkapnya, lihat Memulai Google Play Game.