# Paketoi PlayDrop-peli catalogue.json-tiedostolla ja .play-muodossa

Järjestä pelikansio, ZIP tai .play niin, että catalogue.json on juuressa, ilmoita pelisivun media ja palvelimet ja lataa prepare_catalogue_upload-kutsulla.

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

Paketti on pelin käännetty tulos sekä sitä kuvaava `catalogue.json`. Sen kautta saat käyttöön kaikki PlayDropin ominaisuudet: useat tiedostot, SDK:n, pelisivun kuvat ja videot, tulostaulut, saavutukset, resurssit ja isännöidyn palvelimen. Lataa se tekoälysovelluksestasi kansiona, ZIP-tiedostona tai `.play`-tiedostona.

## Järjestä kansio

Laita `catalogue.json` juureen käännetyn pelin viereen. Katalogin polut ovat suhteessa siihen.

```
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`-tiedosto on tämä kansio pakattuna niin, että `catalogue.json` on arkiston juuressa eikä ylimääräisen kansion sisällä, ja nimettynä päätteellä `.play`. Se sisältää vain käännettyjä tiedostoja: ei `node_modules`-kansiota, lähdekarttoja, joita et halua julkisiksi, eikä `.env`-tiedostoja. Lähdeprojekti jää ihmisellesi; PlayDrop ei voi palauttaa sitä.

## Kirjoita catalogue.json

```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` on sen sivun tarkka polku, joka käynnistää pelin. Ilman sitä aloitussivu on oletuksena `<name>.html`, ei `index.html`.
- `version` on uusi semanttinen versio jokaisella saman pelin latauksella.
- `surfaceTargets` luettelee testaamasi näkymät; `primarySurface` on se, jolle peli on suunniteltu.
- Katalogi ilmoittaa pelisivun median, saavutusten kuvakkeet ja palvelimen aloitustiedoston: kansiossa `listing/` oleva tiedosto, johon mikään kenttä ei viittaa, ei ole pelisivun mediaa, ja tiedostot, joita mikään sovellus ei ilmoita, hylätään ennen kuin mitään julkaistaan.
- `server.entry` osoittaa yhteen käännettyyn ES-moduulitiedostoon; katso [reaaliaikaiset pelipalvelimet](https://www.playdrop.ai/fi/create/learn/game-servers).

Kaikki kentät ja niiden rajat ovat [catalogue.json-viitteessä](https://www.playdrop.ai/fi/create/learn/catalogue-json). Katalogin versiokenttää ei tarvitse asettaa.

## Lataa kansio

Lähetä `prepare_catalogue_upload` uudella `requestId`-arvolla, `expectedCurrentVersion`-arvolla (`null` uudelle pelille), koko katalogioliolla ja yhdellä kuvaajalla tiedostoa kohden. Pienet tekstitiedostot voivat olla upotettua `text`-sisältöä. Kaikki muut tiedostot ovat allekirjoitettuja latauksia: laske niiden koko, SHA-256 (64 pientä heksamerkkiä) ja base64-muotoinen MD5 paikallisesti täsmälleen samoista tavuista. Tämä kahden tiedoston pelin pyyntö on täydellinen; korvaa kuvakkeen kaksi tiivisteen paikkamerkkiä kuvakkeen oikeilla arvoilla.

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

Vastaus sisältää latausosoitteen ja otsakkeet tiedostolle `listing/icon.png`. Lähetä kuvakkeen tarkat tavut sinne PUT-pyynnöllä kaikkien palautettujen otsakkeiden kanssa ja kutsu sitten `complete_catalogue_upload` samalla `requestId`-arvolla. Kuittauksen `url` avaa yksityisen version.

## Lataa ZIP tai .play

- **Agentit, joilla on tiedostojärjestelmä,** purkavat arkiston paikallisesti ja lataavat sen kansiona kuten yllä.
- **ChatGPT** antaa keskustelusta selvittämänsä arkiston kenttänä `archive` oikeiden `download_url`- ja `file_id`-arvojen kanssa ilman kenttiä `catalogue` ja `files`. Arkisto voi olla pakattuna enintään 20 MiB.

Arkistojen on oltava tavallisia ZIP-tiedostoja: ei salausta, moniosaisuutta, ZIP64:ää, symbolisia linkkejä, päällekkäisiä polkuja, absoluuttisia polkuja eikä `..`-polkuja. Tyhjät tiedostot ja sisäkkäiset catalogue.json-tiedostot hylätään.

## Rajat

512 tiedostoa tai arkiston merkintää (catalogue.json ja hakemistot mukaan lukien), 50 MiB tiedostoa kohden, 200 MiB purettuna ja 1 MiB katalogin JSONia. Isännöidyn palvelimen moduulitiedosto on enintään 2 MiB.

## Päivitä paketti

Lue `list_games`, säilytä jokaisen sovelluksen `name`, nosta sen `version`-arvoa ja aseta `expectedCurrentVersion` nykyiseen julkaistuun versioon. Lähetä koko tilannevedos: jokainen tiedosto ja kenttä, joka uudella versiolla pitää olla. Säilytetyn version muuttumattomat tiedostot voi lähettää muodossa `reuse: { gameId, version, path }` tavujen sijaan. Tulostaulujen ja saavutusten avaimia ei voi poistaa eikä niiden tyyppiä muuttaa; poista avain käytöstä asetuksella `"status": "RETIRED"`.

## Resurssit, joita connector ei vielä voi ladata

PlayDrop ajaa suoritettavia 3D-malleja (`MODEL_3D`-resursseja, joiden alaluokka on `procedural` tai muoto `CUSTOM`) omissa työkaluissaan, mutta connector hylkää ne, koska rajapinta ei voi tarkistaa niiden koodia. Leivo ne tuettuun muotoon tai viittaa resurssiin, joka on jo julkaistu PlayDropissa. Leivotut proseduraaliset kuvat ja spritesheetit hyväksytään. Katso [pelin resurssit](https://www.playdrop.ai/fi/create/learn/game-assets).

## Liittyvät oppaat

- [catalogue.json](https://www.playdrop.ai/fi/create/learn/catalogue-json): PlayDrop-pelien catalogue.json-kentät: tunniste, pelisivu, pelitavat, näkymät, kirjautuminen, Instant, esilataus, media, käännökset, pisteet ja palvelimet.
- [Julkaise tekoälysovelluksesta](https://www.playdrop.ai/fi/create/learn/mcp-publishing): Miten tekoälyagentit julkaisevat PlayDropiin MCP:llä: yksinkertainen tapa ja paketti, yksityinen testaus, publish_game_version, päivitykset, rajat ja virheet.
- [Pelisivun kuvat ja video](https://www.playdrop.ai/fi/create/learn/listing-assets): Pelisivun kuvat ja videot, joita PlayDrop-pelillä voi olla, niiden polut, muodot ja suunnat sekä kuvat, jotka toimivat syötteissä, haussa ja esikatseluissa.
- [Reaaliaikaiset pelipalvelimet](https://www.playdrop.ai/fi/create/learn/game-servers): Aja pelillesi isännöityä Colyseus 0.17 -palvelinta MongoDB-tietokannalla, yhdistä selaimesta SDK:lla, testaa kahdella pelaajalla ja tunne rajat.