catalogue.json: PlayDrop oyun meta verileri ve yerelleştirme
Oyun başlıkları, açıklamalar, tür etiketleri, oyun sayfası medyası, çeviriler ve isteğe bağlı server alanı için PlayDrop Connector referansı.
PlayDrop Connector catalogue.json meta verilerini oyun dosyalarıyla birlikte gönderir; komut satırı aracına gerek yoktur. PlayDrop Cloud bu meta verileri Studio oyunları için yönetir.
prepare_catalogue_upload ile eksiksiz özel yükleme
{
"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>"
}
]
}Bu, yeni bir özel oyun için eksiksiz bir prepare_catalogue_upload isteğidir. Örnek HTML’yi derlediğin oyunla değiştir ve istenen her yükleme için benzersiz bir requestId kullan. catalogue nesnesi catalogue.json içeriğidir; files ve expectedCurrentVersion bu nesnenin dışında, araç isteğine aittir.
apps[].file, bir files[].path ile tam olarak eşleşmelidir. file atlanırsa giriş varsayılan olarak index.html değil <name>.html olur. surfaceTargets, desktop, mobileLandscape ve mobilePortrait boolean değerlerini içeren bir nesnedir; test ettiğin en az bir yüzeyi etkinleştir. Sürümü ve görünürlüğü açıkça belirt. Örnek satır içi bir metin dosyası kullanır; ekler veya imzalı bayt yüklemeleri aynı yolu kullanabilir.
Hazırladıktan sonra istenen dosya baytlarını gönder ve aynı requestId ile complete_catalogue_upload çağır. Test etmek için özel sürümü aç. Güncelleme için list_games oku, aynı name değerini koru, yeni bir version ve tam anlık görüntüyü ver, sonra expectedCurrentVersion[name] değerini sunucunun döndürdüğü güncel herkese açık sürüme (yoksa null) ayarla. Bu bir çakışma kontrolüdür, yüklenen sürüm değildir. Yarıda kalan yüklemeleri özgün istek kimliğiyle tekrar dene. Hazır olduğunda test edilmiş, saklanan sürümü publish_game_version ile yayınla.
Eski tek oyunluk uyumluluk örneği
Aşağıdaki örnek eski tek oyunluk biçimdir. Eksiksiz katalog yüklemeleri birden fazla oyunu, asset’i, paketi ve spesifikasyonu da destekler; güncel şemayı bağlayıcıdan iste. Her güncelleme, açık görünürlük ve sürümle eksiksiz bir anlık görüntü sağlar. Katalogdan atlanan öğeler silinmez.
Güncellerken küçük harfli slug’ı sabit tut. Gerektiğinde bir görünen başlık, doğru bir açıklama, kontroller, kaynak dil ve bilinen etiketler ekle. Aşağıdaki örnek mevcut platform türü etiketini kullanır.
{
"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"]
}]
}Desteklenen alanlar ve sınırlar
name: harf veya rakamla başlayan, 1–100 küçük harf, rakam ya da tire. displayName: boş olmayan başlık. subtitle: en fazla 120 karakter. description: H1 başlıkları, gömülü medya veya tablolar olmadan en fazla 3.000 karakterlik Markdown. inspirationPrompt: tek satırlık düz metinden en fazla 400 karakter. Metin sınırları JavaScript UTF-16 kod birimlerini sayar.
İsteğe bağlı alanlar arasında controls, releaseNotes, makingOf, emoji, color, sourceRepository, license, tags, sourceLocale, listingLocalizations, listingMedia ve server bulunur. Etiketler mevcut group-slug/tag-slug referanslarını kullanır, en fazla 20 benzersiz etiketle. server, yüklenen bir server.js dosyasının Colyseus odalarını listeler; örneğin "server": { "rooms": ["game"] }; sunucu SDK’sına bak. Yayınlamadan önce güncel kabul edilen lisans değerlerini ve tam alan kurallarını bağlayıcıdan iste. İsteğe bağlı yerel uygulama ipuçları: prefetch, PlayDrop’un iOS, macOS ve Android uygulamalarının oynamadan önce indirebileceği yüklenmiş dosyaları listeler; örneğin "prefetch": { "required": ["game.js"], "optional": ["music.mp3"] } (giriş sayfası her zaman dahildir) ve "offlineSupported": true, gerekli dosyaları depolandıktan sonra bu uygulamaların oyunu çevrimdışı sunmasını sağlar. Geçersiz değerler yok sayılır ve bir yüklemeyi asla engellemez; web siteleri oyunları her zamanki gibi yükler.
Instant oyunlar: oyun, en fazla 10 MB başlangıç dosyasından (giriş sayfası artı prefetch.required, hiçbiri listelenmemişse yüklenen her dosya) 2 saniye içinde oynanabiliyorsa "instant": true ayarla. Instant oyunlar şimşek rozeti taşır ve PlayDrop’un telefon uygulamalarındaki Instant akışında oynanır. Daha derin seviyeleri ve ekstraları prefetch.optional içine koy, ready() çağırmadan önce gölgelendirici derlemeyi ve diğer ısınmayı bitir, önizlemenin başlık ekranı yerine oynanışı göstermesini sağla ve herkesin oyunu akışta görmesi için misafirlere izin ver (authMode OPTIONAL veya NONE). PlayDrop boyutu yüklemede kontrol eder ve telefonların yavaş başlattığı sürümlerden rozeti kaldırır; çıtayı geçemeyen bir oyun yine de yayınlanır.
Oyun sayfası görselleri ve videoları
Oyun sayfası medyasını index.html dosyasının yanına, yolla adlandırılmış dosyalar olarak yükle: listing/icon.png, sanatın içinde oyun başlığı olan listing/hero-landscape.png (16:9) ve listing/hero-portrait.png (9:16), listing/screenshots/landscape/0.png gibi ekran görüntüleri ve listing/videos/landscape/0.mp4 (fragman) ile listing/videos/portrait/0.mp4 (mobil teaser) videoları. Videolar oyun kartlarında ve oyun sayfasında sessiz oynar; fragman bilgisayarlarda ve TV’de, teaser telefonlarda. Bu yüzden oynanışı göstermenin ve ilk oynanışı kazanmanın en hızlı yoludur. Görseller PNG, videolar MP4’tür.
Oyun sayfasını doğru çevir
Her zaman İngilizceyi ve farklıysa kendi dilini de yayınla. sourceLocale değerini özgün dile ayarla. listingLocalizations İngilizce, Fransızca, Almanca, İspanyolca, Brezilya Portekizcesi, Endonezce, Japonca, Korece, Geleneksel Çince ve Basitleştirilmiş Çinceyi destekler. Her çeviri için locale ve displayName gerekir; kaynağıyla yüklediğinde PlayDrop sourceHash değerini doldurur. Çevrilmiş sanatı listing/locales/<locale>/ altına yükle; örneğin Fransızca başlıklı listing/locales/fr/hero-landscape.png; çevirisiyle otomatik eşleşir. Kaynak değişikliklerinden sonra çevirileri yenile. Oyun sayfası çevirisi oyunun kendisini çevirmez.
Oyuncular, partiler ve kumandalar
Oyununun nasıl oynandığını her oyun girişinde types, party, controller ve roomVoice ile bildir:
{
"types": ["solo", "online", "party"],
"party": { "local": [1, 2, 3, 4], "online": [1, 2, 3, 4] },
"controller": { "support": "optional", "type": "simpler" },
"roomVoice": true
}types, solo (tek başına oynanabilir), online (ağ üzerinden başkalarıyla oynanır) ve party (birlikte oynayan bir grup) değerlerini birleştirir. party.local, tek ekranda oynayabilen kişi sayılarını tam olarak listeler; party.online, çevrimiçi birlikte girebilen arkadaş grubu boyutlarını (en fazla 4) listeler, oda kapasitesini değil. Boyutlar tamdır: [2, 4], 3’ü dışlar. party için party türü, party.online için online gerekir ve party.local içindeki bir 1 için solo gerekir. roomVoice: true oda sesli sohbetini açar ve online gerektirir.
controller.support değeri off (controller atlandığında varsayılan), optional veya required olur. off olmadığında controller.type, oyunun ihtiyaç duyduğu en düşük kontrolleri belirtir:
any: yönler, Onayla ve İptal; uzaktan kumandalar dahil her kumanda çalışır.simpler: bir analog çubuk, dört ön düğme ve Menü; PlayDrop telefon kumandaları ve standart gamepad’ler uygundur.standard: D-pad, iki tıklanabilir çubuk, dört ön düğme, iki omuz düğmesi, iki tetik ve Menü.custom: oyuna özel telefon kontrolleri için ayrılmıştır; henüz kullanılamaz.
Kumanda desteği açıkken bildirilen her yerel sayı kumandalarla oynanabilir olmalıdır; kumanda girdisini SDK üzerinden oku. Mevcut oyunlar hâlâ çalışan players ve controllerMode alanlarını tutabilir ama yeni oyunlar bu alanları kullanır ve bir giriş ikisini karıştıramaz. Ana uygulama yerel ya da çevrimiçi oyunu seçer, asla ikisini birden seçmez. Bu bildirimler Cloud, CLI ve MCP yüklemelerinden, saklanan özel sürümlerden ve yayınlamadan sonra da korunur. Kullanılabilirlik ayrıca platformun kullanıma açılışına ve ana uygulama sürümüne bağlıdır.
MCP sunucu yüklemeleri için derlenmiş bir ESM .mjs/.js paketini SERVER tanımlayıcısı olarak ver ve server.entry değerini ona yönlendir. Cloud/CLI kaynak projeleri TypeScript girişlerini korur. Colyseus ve sunucu SDK çalışma zamanını PlayDrop sağlar; bir oyuna asla sesli sohbet sağlayıcısı kimlik bilgileri ekleme.