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

Dapatkan Input SDK untuk Java atau Kotlin dengan menambahkan dependensi ke file build.gradle level modul (ini kemungkinan ada di direktori app Anda):

dependencies {
  implementation 'com.google.android.libraries.play.games:inputmapping:1.0.0-beta'
  ...
}

Input SDK untuk Unity belum tersedia untuk didownload. Library ini akan tersedia sebagai 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:

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

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

private class MyInputMappingProvider : PlayInputMappingProvider
{
    public PlayInputMap 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:

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

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

var jumpInputAction = PlayInputAction.Create(
    "Jump",
    (int)InputEventIds.Jump,
    PlayInputControls.Create(
        new[]
        {
            AndroidKeyCode.KEYCODE_SPACE
        },
        null
    )
);

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

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

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

var cmbMove = PlayInputAction.Create(
    "Move",
    (int)InputEventIds.CmbMove,
    PlayInputControls.Create(
        null,
        new[]
        {
            PlayMouseAction.MouseRightClick
        }
    )
);

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.

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

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

var cmbDash = PlayInputAction.Create(
    "Dash",
    (int)InputEventIds.CmbDash,
    PlayInputControls.Create(
        new[]
        {
            AndroidKeyCode.KEYCODE_SPACE, AndroidKeyCode.KEYCODE_SHIFT_LEFT
        }, null
    )
);

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:

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

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

var cmbWaypoint = PlayInputAction.Create(
    "Add Waypoint",
    (int)InputEventIds.CmbWaypoint,
    PlayInputControls.Create(
        new[]
        {
            AndroidKeyCode.KEYCODE_SHIFT_LEFT
        },
        new[]
        {
            PlayMouseAction.MouseRightClick
        }
    )
);

Bagian ini menjelaskan panggilan metode dalam contoh kode:

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.

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

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

var movementInputGroup = PlayInputGroup.Create(
    "Basic Movement",
    new[]
    {
        jumpInputAction, leftInputAction, rightInputAction, useInputAction
    }
);

Bagian ini menjelaskan panggilan metode yang digunakan dalam contoh kode:

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:

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

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

return PlayInputMap.Create(
    new[]
    {
        movementInputGroup, specialInputGroup, combinationInputGroup
    },
    PlayMouseSettings.Create(true, false)
);

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.

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

    val inputMappingClient = Input.getInputMappingClient(this)
    inputMappingClient.setInputMappingProvider(MyInputMapProvider())
}

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

    InputMappingClient inputMappingClient = Input.getInputMappingClient(this);
    inputMappingClient.setInputMappingProvider(new MyInputMapProvider());
}

void Start()
{
    _inputMappingProvider = new MyInputMappingProvider();
    PlayInput.GetInputMappingClient().SetInputMappingProvider(_inputMappingProvider);
}

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

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

    super.onDestroy()
}

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

    super.onDestroy();
}

private void OnDestroy()
{
    PlayInput.GetInputMappingClient().ClearInputMappingProvider();
}

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.

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

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

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.

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 setInputMappingProvider 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.