# 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ı.

Source: https://www.playdrop.ai/tr/create/learn/catalogue-json

[PlayDrop Connector](https://www.playdrop.ai/tr/create/connectors) `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

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.

```json
{
  "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>"
    }
  ]
}
```

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

```json
{
  "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](https://www.playdrop.ai/tr/create/learn/server-sdk) 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:

```json
{
  "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](https://www.playdrop.ai/tr/create/learn/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.