Referensi teknis

SDK klien PlayDrop untuk game browser

SDK browser opsional untuk game PlayDrop apa pun: siklus hidup host, login, data simpanan, papan peringkat, pembelian, iklan, teman, pengontrol, multiplayer, dan pustaka bersama, cukup dengan satu tag script.

SDK PlayDrop bersifat opsional: game tanpa SDK tetap bisa dimainkan di PlayDrop. Tambahkan SDK untuk fitur platform seperti login pemain, data simpanan, pencapaian dan papan peringkat, pembelian dengan Kredit, iklan, teman dan kartu game di PlayDrop Chat, tautan berbagi, jeda dan audio yang dikelola host, input pengontrol, multiplayer yang di-hosting, serta pembuatan konten AI. PlayDrop Cloud mengintegrasikannya untuk Anda; dengan PlayDrop Connector, agen Anda cukup menambahkan satu tag script.

Tambahkan SDK dan ikuti siklus hidup host

html

<script src="https://assets.playdrop.ai/sdk/playdrop.js"></script>
<script type="module">
  const sdk = await playdrop.init();
  // Render the game and prepare input, then:
  sdk.host.ready();
  sdk.host.onPause(() => pauseGame());
  sdk.host.onResume(() => resumeGame());
  sdk.host.onAudioPolicyChange(({ enabled }) => setAudioEnabled(enabled));
</script>

Muat SDK dari CDN PlayDrop; tidak perlu menginstal paket apa pun. Render frame pertama yang dapat dimainkan dan siapkan input sebelum memanggil sdk.host.ready(). Jeda simulasi saat host melakukan jeda, lanjutkan kembali tanpa loop duplikat, dan ikuti kebijakan audio host.

Identitas, data simpanan, dan bahasa

sdk.me menyediakan identitas pemain dan sdk.me.appData menyimpan data simpanan privat; sdk.achievements dan sdk.leaderboards menangani pencapaian dan skor. Data simpanan, pencapaian, dan papan peringkat berfungsi tanpa pemeriksaan login terlebih dahulu. Gunakan sdk.me.isLoggedIn untuk fitur yang memerlukan akun sungguhan, seperti pembelian atau multiplayer. Mode pratinjau dan mode capture tidak boleh menulis progres pemain. sdk.host.language memberikan bahasa pemain: sediakan bahasa Inggris ditambah bahasa Anda sendiri jika berbeda. Menerjemahkan listingan tidak menerjemahkan konten game. Pada jeda alami, misalnya setelah menang, sdk.host.requestReview() membiarkan PlayDrop meminta ulasan dari pemain, paling banyak sekali per game; game Anda tidak pernah tahu jawabannya, jadi jangan pernah memberi hadiah untuknya.

Pustaka, aset, dan multiplayer

sdk.libs memuat versi Three.js, Phaser, Rapier, nipplejs, dan Colyseus yang didukung. sdk.assets menyediakan referensi katalog, pack, dan aset; sdk.social menyediakan teman, kartu game, dan aksi berbagi. Untuk multiplayer yang di-hosting, sdk.multiplayer.getConnection() mengembalikan alamat server dan token pemain yang sedang login; bergabunglah dengan klien Colyseus. Halaman SDK server membahas server yang di-hosting; server yang Anda jalankan sendiri tidak memerlukan apa pun dari SDK. API room relay yang lama sudah dihentikan.

Uji dengan SDK sebelum memublikasikan

Jalankan server dev seperti biasa dan buka https://www.playdrop.ai/creators/<username>/apps/game/<slug>/dev?url=http://localhost:5173/ di Chrome untuk memainkannya di dalam frame PlayDrop yang sebenarnya dengan host SDK. Port localhost atau URL https apa pun dapat digunakan. Fitur yang memerlukan akun, seperti data simpanan dan pembelian, berfungsi setelah game diunggah sekali; unggahan privat sudah cukup. Pembuatan media di browser berjalan sebagai tugas asinkron dengan biaya Kredit yang dikonfirmasi oleh host. Lihat catalogue.json untuk metadata listingan.

Bermain bersama

Saat bermain, gunakan await sdk.multiplayer.join("game") untuk bergabung sendiri atau memakai reservasi grup dari host. Kegagalan grup menolak permintaan, bukan memisahkan pemain ke ruangan lain. getConnection() tetap langsung menyediakan detail koneksi bagi game lama. Pertahankan ruangan yang sama antar ronde dan jaringan tetap aktif saat antarmuka host menjeda input game.

Panggil sdk.social.openParty() dari tindakan pemain untuk membuka grup di host. Baca anggota melalui await sdk.social.getParty() atau sdk.social.onPartyChange(callback). Game tidak dapat mengubah grup platform atau mengontrol mikrofon. Suara dikelola host web atau native, sesuai persetujuan, pembisuan, pemblokiran, dan ketersediaan fitur.

Untuk suara spasial yang lancar, panggil sdk.multiplayer.voice.updateSpatialState({ listener: { position, forward, up }, speakers: [{ userId, position }] }) dengan vektor { x, y, z } bernilai hingga. Petunjuk memengaruhi volume dan posisi stereo, bukan otorisasi. Server menerapkan ketentuan tim dan jarak.

Gunakan sdk.device.localPlayers dan sdk.device.onLocalPlayersChange(callback) untuk slot pengontrol lokal yang dipilih { playerIndex, gamepadKey }. Daftar pengontrol terhubung terpisah; slot yang terputus tetap memiliki identitasnya. Mode lokal tidak dapat bergabung ke ruangan online. Resep yang dapat disalin playdrop-metagame/recipes/play-together menunjukkan kedua mode, dua tujuan, dan kebijakan ruangan.

Pengontrol

Baca pengontrol fisik dan pengontrol ponsel PlayDrop melalui sdk.device, dengan cara yang sama di setiap platform. Panggil enableControllerInput() sekali setelah init(), baca gamepad(playerIndex) di loop game (0 adalah P1), dan gunakan onButton untuk tombol yang ditekan dan dilepas. Sumbu dan tombol mengikuti urutan gamepad standar browser; tombol memiliki nama posisi seperti south dan east, dan pad.label("south") mengembalikan label untuk pengontrol tersebut, misalnya "A" atau "Cross". Tombol Menu milik PlayDrop dan menjeda game.

await sdk.device.enableControllerInput();
const stop = sdk.device.onButton(({ playerIndex, button, pressed }) => {
  if (button === "south" && pressed) jump(playerIndex);
});
function update() {
  const pad = sdk.device.gamepad(0);
  if (pad?.connected) move(pad.axes[0], pad.axes[1]);
  requestAnimationFrame(update);
}
update();

Jangan memanggil navigator.getGamepads(): pengontrol ponsel hanya sampai ke game melalui SDK, dan PlayDrop mencatat peringatan saat game membaca API browser secara langsung. Jika host tidak dapat menyediakan input pengontrol, enableControllerInput() ditolak dengan controller_input_unavailable atau controller_input_timeout dan game tetap berjalan. pad.has("dpad") menunjukkan apakah sebuah kontrol tersedia; deklarasikan kontrol yang dibutuhkan game Anda di catalogue.json.