catalogue.json: metadata dan lokalisasi game PlayDrop
Referensi untuk judul game, deskripsi, tag genre, gambar dan video listingan, terjemahan, serta field server opsional dalam format PlayDrop Connector.
PlayDrop Connector mengirim metadata catalogue.json bersama berkas game; tidak perlu alat command-line. PlayDrop Cloud mengelola metadata ini untuk game Studio.
Unggahan privat lengkap dengan prepare_catalogue_upload
{
"requestId": "my-game-v1-unique-request",
"catalogue": {
"apps": [
{
"name": "my-game",
"displayName": "My Game",
"file": "index.html",
"version": "1.0.0",
"visibility": "PRIVATE",
"authMode": "OPTIONAL",
"surfaceTargets": {
"desktop": true,
"mobileLandscape": false,
"mobilePortrait": false
}
}
]
},
"expectedCurrentVersion": {
"my-game": null
},
"files": [
{
"path": "index.html",
"text": "<!doctype html><html><head><title>My Game</title></head><body><button onclick=\"this.textContent=Number(this.textContent)+1\">0</button></body></html>"
}
]
}Ini adalah permintaan prepare_catalogue_upload lengkap untuk game privat baru. Ganti HTML contoh dengan game yang sudah dibangun dan gunakan requestId unik untuk setiap unggahan yang direncanakan. Objek catalogue berisi catalogue.json; files dan expectedCurrentVersion berada di permintaan alat, di luar objek itu.
apps[].file harus persis sesuai dengan salah satu files[].path. Jika file dihilangkan, jalur bawaan adalah <name>.html, bukan index.html. surfaceTargets adalah objek dengan boolean desktop, mobileLandscape, dan mobilePortrait; aktifkan setidaknya satu permukaan yang telah diuji. Nyatakan versi dan visibilitas secara eksplisit. Contoh ini memakai teks langsung; lampiran atau unggahan bertanda tangan dapat memakai jalur yang sama.
Setelah persiapan, kirim isi file yang diminta lalu panggil complete_catalogue_upload dengan requestId yang sama. Buka versi privat untuk mengujinya. Untuk memperbarui, baca list_games, pertahankan name, berikan version baru dan snapshot lengkap, lalu isi expectedCurrentVersion[name] dengan versi publik saat ini dari server, atau null jika belum ada. Ini memeriksa konflik, bukan menentukan versi yang diunggah. Lanjutkan unggahan terputus dengan ID permintaan aslinya. Publikasikan versi tersimpan yang telah diuji memakai publish_game_version saat siap.
Contoh kompatibilitas format lama untuk satu game
Contoh berikut memakai format lama untuk satu game. Katalog lengkap juga mendukung banyak game, aset, paket, dan spesifikasi; minta skema terkini dari konektor. Setiap pembaruan mengirim snapshot lengkap dengan versi dan visibilitas yang dinyatakan jelas. Item katalog yang tidak disertakan tidak dihapus.
Pastikan slug huruf kecil tetap sama saat memperbarui. Tambahkan judul tampilan, deskripsi yang akurat, kontrol, bahasa sumber, dan tag yang dikenal sesuai kebutuhan. Contoh di bawah ini menggunakan tag genre platformer yang sudah ada.
{
"apps": [{
"name": "moon-jump",
"displayName": "Moon Jump",
"description": "Jump between lunar platforms and reach the finish.",
"controls": "Arrow keys to move. Space to jump.",
"sourceLocale": "en",
"tags": ["game-genre/platformer"]
}]
}Field yang didukung dan batasannya
name: 1–100 huruf kecil, angka, atau tanda hubung, diawali dengan huruf atau angka. displayName: judul yang tidak kosong. subtitle: maksimal 120 karakter. description: maksimal 3,000 karakter Markdown, tanpa heading H1, media yang disematkan, atau tabel. inspirationPrompt: maksimal 400 karakter teks biasa dalam satu baris. Batas teks dihitung dalam unit kode UTF-16 JavaScript.
Field opsional meliputi controls, releaseNotes, makingOf, emoji, color, sourceRepository, license, tags, sourceLocale, listingLocalizations, listingMedia, dan server. Tag menggunakan referensi group-slug/tag-slug yang sudah ada, dengan maksimal 20 tag unik. server mencantumkan room Colyseus dari server.js yang diunggah, misalnya "server": { "rooms": ["game"] }; lihat SDK server. Sebelum publikasi, tanyakan kepada konektor nilai lisensi yang saat ini diterima dan aturan field selengkapnya. Petunjuk opsional untuk aplikasi native: prefetch mencantumkan file yang diunggah yang dapat diunduh aplikasi PlayDrop untuk iOS, macOS, dan Android sebelum bermain, misalnya "prefetch": { "required": ["game.js"], "optional": ["music.mp3"] } (halaman masuk selalu disertakan), dan "offlineSupported": true memungkinkan aplikasi tersebut menawarkan game secara offline setelah file wajibnya tersimpan. Nilai yang tidak valid diabaikan dan tidak pernah memblokir unggahan; situs web memuat game seperti biasa.
Game instan: tetapkan "instant": true jika game dapat dimainkan dalam 2 detik dengan file awal paling banyak 10 MB (halaman masuk ditambah prefetch.required, atau semua file yang diunggah jika tidak ada yang dicantumkan). Game instan memiliki lencana petir dan dimainkan di feed Instan aplikasi ponsel PlayDrop. Letakkan level lanjutan dan ekstra di prefetch.optional, selesaikan kompilasi shader dan persiapan lain sebelum memanggil ready(), pastikan pratinjau menampilkan gameplay, bukan layar judul, dan izinkan tamu (authMode OPTIONAL atau NONE) agar semua orang melihat game di feed. PlayDrop memeriksa ukuran saat unggah dan mencabut lencana dari versi yang lambat dimulai di ponsel; game yang tidak memenuhi batas tetap diterbitkan.
Gambar dan video listingan
Unggah media listingan sebagai file di samping index.html, dengan nama sesuai path: listing/icon.png, listing/hero-landscape.png (16:9), dan listing/hero-portrait.png (9:16) dengan judul game di dalam artwork-nya, screenshot seperti listing/screenshots/landscape/0.png, serta video listing/videos/landscape/0.mp4 (trailer) dan listing/videos/portrait/0.mp4 (teaser untuk ponsel). Video diputar tanpa suara di kartu game dan halaman game (trailer di komputer dan TV, teaser di ponsel), sehingga video adalah cara tercepat untuk menunjukkan gameplay dan mendapatkan permainan pertama. Gambar berformat PNG dan video berformat MP4.
Terjemahkan listingan secara akurat
Selalu publikasikan dalam bahasa Inggris ditambah bahasa Anda sendiri jika berbeda. Atur sourceLocale ke bahasa asli. listingLocalizations mendukung bahasa Inggris, Prancis, Jerman, Spanyol, Portugis Brasil, Indonesia, Jepang, Korea, Tionghoa Tradisional, dan Tionghoa Sederhana. Setiap terjemahan memerlukan locale dan displayName; saat Anda mengunggahnya bersama sumbernya, PlayDrop mengisi sourceHash. Unggah artwork terjemahan di bawah listing/locales/<locale>/, misalnya listing/locales/fr/hero-landscape.png dengan judul dalam bahasa Prancis; artwork tersebut dicocokkan dengan terjemahannya secara otomatis. Perbarui terjemahan setelah sumber berubah. Terjemahan listingan tidak menerjemahkan game itu sendiri.
Pemain, grup, dan pengontrol
Deklarasikan cara game dimainkan dengan types, party, controller, dan roomVoice di setiap entri game:
{
"types": ["solo", "online", "party"],
"party": { "local": [1, 2, 3, 4], "online": [1, 2, 3, 4] },
"controller": { "support": "optional", "type": "simpler" },
"roomVoice": true
}types menggabungkan solo (dapat dimainkan sendiri), online (dimainkan bersama orang lain melalui jaringan), dan party (sekelompok orang bermain bersama). party.local mencantumkan jumlah pasti orang yang dapat bermain di satu layar; party.online mencantumkan ukuran grup teman, hingga 4, yang dapat masuk online bersama, bukan kapasitas ruangan. Ukuran bersifat pasti: [2, 4] tidak mencakup 3. party memerlukan tipe party, party.online memerlukan online, dan angka 1 di party.local memerlukan solo. roomVoice: true mengaktifkan suara ruangan dan memerlukan online.
controller.support bernilai off (bawaan jika controller dihilangkan), optional, atau required. Jika bukan off, controller.type menyebutkan kontrol minimum yang dibutuhkan game:
any: arah, Konfirmasi, dan Batal; semua pengontrol bisa dipakai, termasuk remote.simpler: satu stik analog, empat tombol aksi, dan Menu; pengontrol ponsel PlayDrop dan gamepad standar memenuhi syarat.standard: D-pad, dua stik yang bisa ditekan, empat tombol aksi, dua tombol bahu, dua pemicu, dan Menu.custom: dicadangkan untuk kontrol ponsel khusus game; belum tersedia.
Jika dukungan pengontrol aktif, setiap jumlah lokal yang dideklarasikan harus dapat dimainkan dengan pengontrol; baca input pengontrol melalui SDK. Game yang sudah ada boleh tetap memakai players dan controllerMode, yang masih berfungsi, tetapi game baru memakai field ini, dan satu entri tidak boleh mencampur keduanya. Host memilih lokal atau online, bukan keduanya. Deklarasi dipertahankan dalam unggahan Cloud, CLI dan MCP, versi privat tersimpan, dan publikasi. Ketersediaan juga bergantung pada peluncuran platform dan versi host.
Untuk unggahan server MCP, sediakan bundle ESM terbangun .mjs/.js sebagai deskriptor SERVER dan arahkan server.entry ke sana. Proyek sumber Cloud/CLI mempertahankan entri TypeScript. PlayDrop menyediakan Colyseus dan runtime SDK server; jangan pernah menyertakan kredensial penyedia suara dalam game.