# PlayDrop oyununu catalogue.json ve .play ile paketle

Kökünde catalogue.json olan derlenmiş bir klasör, ZIP ya da .play hazırla, oyun sayfası medyasını ve sunucuları bildir, prepare_catalogue_upload ile yükle.

Source: https://www.playdrop.ai/tr/create/learn/packaging

Paket, bir oyunun derlenmiş çıktısı ve onu tanımlayan bir `catalogue.json` dosyasıdır. Her PlayDrop özelliğinin yolu budur: birden fazla dosya, SDK, oyun sayfası görselleri ve videoları, liderlik tabloları, başarımlar, asset’ler ve barındırılan bir sunucu. Onu yapay zeka uygulamandan klasör, ZIP ya da `.play` dosyası olarak yükle.

## Klasörü düzenle

`catalogue.json` dosyasını köke, derlenmiş oyunun yanına koy. Katalogdaki yollar ona göre görelidir.

```
catalogue.json
index.html
assets/sprites.png
assets/music.mp3
listing/icon.png
listing/hero-landscape.png
listing/hero-portrait.png
listing/screenshots/landscape-1.png
listing/videos/portrait-1.mp4
achievements/first-win.png
server/index.mjs
```

`.play` dosyası, `catalogue.json` bir sarmalayıcı klasörün içinde değil arşivin kökünde olacak şekilde ZIP’lenmiş ve uzantısı `.play` olarak değiştirilmiş bu klasördür. Yalnızca derlenmiş dosyalar içerir: `node_modules`, herkese açık olmasını istemediğin kaynak haritaları ya da `.env` dosyaları olmaz. Kaynak projeyi kullanıcında tut; PlayDrop onu geri veremez.

## catalogue.json yaz

```json
{
  "apps": [{
    "name": "moon-jump",
    "displayName": "Moon Jump",
    "subtitle": "Lunar platform hopping against the clock",
    "description": "Jump between lunar platforms, collect oxygen and reach the flag.",
    "controls": "Tap or press Space to jump. Swipe or use arrows to steer.",
    "file": "index.html",
    "version": "1.0.0",
    "visibility": "PRIVATE",
    "authMode": "OPTIONAL",
    "tags": ["game-genre/casual", "game-genre/platformer"],
    "types": ["solo"],
    "controller": { "support": "optional", "type": "simpler" },
    "surfaceTargets": { "desktop": true, "mobileLandscape": true, "mobilePortrait": true },
    "primarySurface": "MOBILE_PORTRAIT",
    "sourceLocale": "en",
    "listing": {
      "icon": "listing/icon.png",
      "heroLandscape": "listing/hero-landscape.png",
      "heroPortrait": "listing/hero-portrait.png",
      "screenshotsLandscape": ["listing/screenshots/landscape-1.png"],
      "videosPortrait": ["listing/videos/portrait-1.mp4"]
    },
    "leaderboards": [{ "key": "best-time", "displayName": "Best time", "description": "Fastest run to the flag",
      "scoreType": "TIME_MS", "sort": "ASC" }],
    "achievements": [{ "key": "first-win", "displayName": "First flag", "description": "Reach the flag once",
      "kind": "STANDARD", "icon": "achievements/first-win.png" }],
    "server": { "entry": "server/index.mjs", "rooms": ["game"] }
  }]
}
```

- `file`, oyunu başlatan sayfanın tam yoludur. Yoksa giriş varsayılan olarak `index.html` değil, `<name>.html` olur.
- `version`, aynı oyunun her yüklemesi için yeni bir anlamsal sürümdür.
- `surfaceTargets` test ettiğin yüzeyleri listeler; `primarySurface` oyunun tasarlandığı yüzeydir.
- Oyun sayfası medyası, başarım simgeleri ve sunucu girişi katalog tarafından sahiplenilir: `listing/` altında olup hiçbir alanın referans vermediği bir dosya oyun sayfası medyası değildir ve hiçbir uygulamanın sahiplenmediği dosyalar herhangi bir şey yayınlanmadan önce reddedilir.
- `server.entry`, derlenmiş tek bir ES modülü paketini gösterir; bkz. [gerçek zamanlı oyun sunucuları](https://www.playdrop.ai/tr/create/learn/game-servers).

Her alan ve sınırları [catalogue.json başvurusunda](https://www.playdrop.ai/tr/create/learn/catalogue-json). Ayarlanacak bir katalog sürümü alanı yoktur.

## Bir klasör yükle

`prepare_catalogue_upload` isteğini yeni bir `requestId`, `expectedCurrentVersion` (yeni bir oyun için `null`), eksiksiz katalog nesnesi ve her dosya için bir tanımlayıcıyla gönder. Küçük metin dosyaları satır içi `text` olabilir. Diğer her dosya imzalı bir yüklemedir: boyutunu, SHA-256 değerini (64 küçük harfli onaltılık karakter) ve base64 MD5 değerini tam baytlardan yerelde hesapla. İki dosyalık bir oyun için bu istek eksiksizdir; simgedeki iki özet yer tutucusunu simgenin gerçek değerleriyle değiştir.

```json
{
  "requestId": "moon-jump-1.0.0",
  "expectedCurrentVersion": { "moon-jump": null },
  "catalogue": {
    "apps": [{
      "name": "moon-jump",
      "displayName": "Moon Jump",
      "file": "index.html",
      "version": "1.0.0",
      "visibility": "PRIVATE",
      "authMode": "OPTIONAL",
      "tags": ["game-genre/casual"],
      "types": ["solo"],
      "controller": { "support": "off" },
      "surfaceTargets": { "desktop": true, "mobileLandscape": false, "mobilePortrait": true },
      "listing": { "icon": "listing/icon.png" }
    }]
  },
  "files": [
    { "path": "index.html",
      "text": "<!doctype html><html><head><meta charset=\"utf-8\"><title>Moon Jump</title></head><body><canvas id=\"game\"></canvas><script>/* built game */</script></body></html>" },
    { "path": "listing/icon.png", "contentType": "image/png", "sizeBytes": 50211,
      "sha256": "REPLACE_WITH_ICON_SHA256_HEX", "md5Base64": "REPLACE_WITH_ICON_MD5_BASE64" }
  ]
}
```

Yanıt, `listing/icon.png` için bir yükleme URL’si ve başlıkları listeler. Simgenin tam baytlarını döndürülen her başlıkla oraya PUT ile gönder, sonra `complete_catalogue_upload` aracını aynı `requestId` ile çağır. Makbuzdaki `url` özel sürümü açar.

## ZIP veya .play yükle

- **Dosya sistemi olan ajanlar** arşivi yerelde açar ve yukarıdaki gibi klasör olarak yükler.
- **ChatGPT**, sohbetten çözümlediği arşivi gerçek `download_url` ve `file_id` değerleriyle, `catalogue` ya da `files` olmadan `archive` olarak geçirir. Arşivin sıkıştırılmış hali 20 MiB’a kadar olabilir.

Arşivler sıradan ZIP dosyaları olmalıdır: şifreleme, birden çok parça, ZIP64, sembolik bağlantı, yinelenen yol, mutlak yol ya da `..` olmaz. Boş dosyalar ve iç içe catalogue.json dosyaları reddedilir.

## Sınırlar

512 dosya ya da arşiv girdisi (catalogue.json ve dizinler dahil), dosya başına 50 MiB, açılmış halde 200 MiB ve 1 MiB katalog JSON’u. Barındırılan bir sunucu paketi en fazla 2 MiB’tır.

## Bir paketi güncelle

`list_games` oku, her uygulamanın `name` değerini koru, `version` değerini yükselt ve `expectedCurrentVersion` değerini güncel yayınlanmış sürüme ayarla. Tam anlık görüntüyü gönder: yeni sürümün sahip olması gereken her dosya ve alan. Saklanan bir sürümün değişmemiş dosyaları, baytları yerine `reuse: { gameId, version, path }` ile gönderilebilir. Liderlik tablosu ve başarım anahtarları kaldırılamaz ve türleri değiştirilemez; birini `"status": "RETIRED"` ile kullanımdan kaldır.

## Bağlayıcının henüz yükleyemediği asset’ler

PlayDrop çalıştırılabilir 3D modelleri (`procedural` alt kategorili ya da `CUSTOM` biçimli `MODEL_3D` asset’leri) kendi araçlarında çalıştırır, ancak API kodlarını doğrulayamadığı için bağlayıcı onları reddeder. Onları desteklenen bir biçime dönüştür ya da PlayDrop’ta zaten yayınlanmış bir asset’e referans ver. Sabit biçime dönüştürülmüş prosedürel görseller ve sprite sayfaları kabul edilir. Bkz. [oyun asset’leri](https://www.playdrop.ai/tr/create/learn/game-assets).

## İlgili kılavuzlar

- [catalogue.json](https://www.playdrop.ai/tr/create/learn/catalogue-json): PlayDrop oyunlarının kullandığı catalogue.json alanları: kimlik, oyun sayfası, oynanış modları, yüzeyler, giriş, Instant, ön yükleme, medya, çeviriler, skorlar ve sunucular.
- [Yapay zeka uygulamandan yayınla](https://www.playdrop.ai/tr/create/learn/mcp-publishing): Yapay zeka ajanları PlayDrop’a MCP ile nasıl yayınlar: basit yol ve paket yolu, özel test, publish_game_version, güncellemeler, sınırlar ve kurtarma.
- [Oyun sayfası görselleri ve video](https://www.playdrop.ai/tr/create/learn/listing-assets): Oyun sayfası görselleri ve videoları: yollar, biçimler ve yönler; akışlarda, aramada ve bağlantı önizlemelerinde işe yarayan görseller nasıl yapılır.
- [Gerçek zamanlı oyun sunucuları](https://www.playdrop.ai/tr/create/learn/game-servers): Oyunun için MongoDB veritabanlı, barındırılan bir Colyseus 0.17 sunucusu çalıştır, tarayıcıdan SDK ile bağlan, iki oyuncuyla test et ve sınırları öğren.