# Crea il pacchetto di un gioco PlayDrop con catalogue.json e .play

Organizza una cartella compilata, uno ZIP o un .play con catalogue.json nella radice, dichiara scheda e server e caricalo con prepare_catalogue_upload.

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

Un pacchetto è il risultato compilato di un gioco più un `catalogue.json` che lo descrive. È il percorso per ogni funzione di PlayDrop: più file, l’SDK, immagini e video della scheda, classifiche, obiettivi, asset e un server ospitato. Caricalo dalla tua app di IA come cartella, ZIP o file `.play`.

## Organizza la cartella

Metti `catalogue.json` nella radice, accanto al gioco compilato. I percorsi nel catalogo sono relativi a quel file.

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

Un file `.play` è questa cartella compressa in ZIP con `catalogue.json` nella radice dell’archivio, non dentro una cartella contenitore, e rinominata in `.play`. Contiene solo file compilati: niente `node_modules`, niente source map che non vuoi rendere pubbliche e niente file `.env`. Il progetto sorgente resta in mano al tuo utente; PlayDrop non può restituirlo.

## Scrivi 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` è il percorso esatto della pagina che avvia il gioco. Senza di esso, la pagina di ingresso predefinita è `<name>.html`, non `index.html`.
- `version` è una nuova versione semantica per ogni caricamento dello stesso gioco.
- `surfaceTargets` elenca le superfici che hai testato; `primarySurface` è quella per cui è pensato il gioco.
- I contenuti della scheda, le icone degli obiettivi e la voce del server devono essere dichiarati nel catalogo: un file in `listing/` a cui nessun campo fa riferimento non è un contenuto della scheda, e i file che nessuna app dichiara vengono rifiutati prima che venga pubblicato qualcosa.
- `server.entry` punta a un unico bundle compilato come modulo ES; vedi [server di gioco in tempo reale](https://www.playdrop.ai/it/create/learn/game-servers).

Tutti i campi e i loro limiti sono nel [riferimento di catalogue.json](https://www.playdrop.ai/it/create/learn/catalogue-json). Non esiste un campo per la versione del catalogo da impostare.

## Carica una cartella

Invia `prepare_catalogue_upload` con un nuovo `requestId`, `expectedCurrentVersion` (`null` per un nuovo gioco), l’oggetto completo del catalogo e un descrittore per file. I file di testo piccoli possono essere `text` in linea. Ogni altro file è un caricamento firmato: calcola in locale dai byte esatti la dimensione, lo SHA-256 (64 caratteri esadecimali minuscoli) e l’MD5 in base64. Questa richiesta per un gioco di due file è completa; sostituisci i due segnaposto dei digest dell’icona con i valori reali dell’icona.

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

La risposta elenca un URL di caricamento e le intestazioni per `listing/icon.png`. Invia lì con PUT i byte esatti dell’icona con tutte le intestazioni restituite, poi chiama `complete_catalogue_upload` con lo stesso `requestId`. L’`url` della ricevuta apre la versione privata.

## Carica uno ZIP o un .play

- **Gli agenti con accesso al file system** estraggono l’archivio in locale e lo caricano come cartella, come sopra.
- **ChatGPT** passa come `archive` l’archivio che ha risolto dalla conversazione, con i suoi veri `download_url` e `file_id`, senza `catalogue` né `files`. L’archivio può arrivare a 20 MiB compresso.

Gli archivi devono essere normali file ZIP: niente cifratura, volumi multipli, ZIP64, link simbolici, percorsi duplicati, percorsi assoluti o `..`. I file vuoti e i file catalogue.json annidati vengono rifiutati.

## Limiti

512 file o voci dell’archivio (compresi catalogue.json e le cartelle), 50 MiB per file, 200 MiB estratti e 1 MiB di JSON del catalogo. Il bundle di un server ospitato è al massimo di 2 MiB.

## Aggiorna un pacchetto

Leggi `list_games`, mantieni il `name` di ogni app, aumentane la `version` e imposta `expectedCurrentVersion` sulla versione pubblicata attuale. Invia l’istantanea completa: ogni file e campo che la nuova versione deve avere. I file invariati di una versione conservata si possono inviare con `reuse: { gameId, version, path }` invece dei loro byte. Le chiavi di classifiche e obiettivi non si possono rimuovere né cambiare tipo; ritirane una con `"status": "RETIRED"`.

## Asset che il connettore non può ancora caricare

PlayDrop esegue i modelli 3D eseguibili (asset `MODEL_3D` con la sottocategoria `procedural` o il formato `CUSTOM`) nei propri strumenti, ma il connettore li rifiuta perché l’API non può verificarne il codice. Convertili in un formato supportato, oppure fai riferimento a un asset già pubblicato su PlayDrop. Le immagini e gli spritesheet procedurali già convertiti in file statici sono accettati. Vedi [asset di gioco](https://www.playdrop.ai/it/create/learn/game-assets).

## Guide correlate

- [catalogue.json](https://www.playdrop.ai/it/create/learn/catalogue-json): Campi di catalogue.json usati dai giochi PlayDrop: identità, scheda, modalità, superfici, accesso, Instant, precarico, media, traduzioni, punteggi e server.
- [Pubblica dalla tua app di IA](https://www.playdrop.ai/it/create/learn/mcp-publishing): Come le app di IA pubblicano su PlayDrop tramite MCP: percorso semplice e pacchetti, test privati, publish_game_version, aggiornamenti, limiti e recupero.
- [Immagini e video della scheda](https://www.playdrop.ai/it/create/learn/listing-assets): Immagini e video della scheda di un gioco PlayDrop: percorsi, formati, orientamenti e come creare immagini efficaci in feed, ricerca e anteprime dei link.
- [Server in tempo reale](https://www.playdrop.ai/it/create/learn/game-servers): Esegui un server Colyseus 0.17 ospitato con un database MongoDB, collegati dal browser con l’SDK, prova con due giocatori e conosci i limiti.