# catalogue.json: metadati e traduzioni dei giochi PlayDrop

Riferimento per titoli, descrizioni, tag di genere, immagini e video della scheda, traduzioni e campo server facoltativo nel formato di PlayDrop Connector.

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

[PlayDrop Connector](https://www.playdrop.ai/it/create/connectors) invia i metadati di `catalogue.json` insieme ai file del gioco; non serve alcuno strumento a riga di comando. PlayDrop Cloud mantiene questi metadati per i giochi di Studio.

## Caricamento privato completo con prepare_catalogue_upload

Questa è una richiesta `prepare_catalogue_upload` completa per un nuovo gioco privato. Sostituisci l’HTML di esempio con il tuo gioco compilato e usa un `requestId` univoco per ogni caricamento previsto. L’oggetto `catalogue` è il contenuto di `catalogue.json`; `files` e `expectedCurrentVersion` appartengono alla richiesta dello strumento, fuori da quell’oggetto.

```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` deve corrispondere esattamente a un `files[].path`. Se `file` è omesso, la voce usa per default `<name>.html`, non `index.html`. `surfaceTargets` è un oggetto con i booleani `desktop`, `mobileLandscape` e `mobilePortrait`; attiva almeno una superficie che hai provato. Dichiara esplicitamente versione e visibilità. L’esempio usa un file di testo inline; gli allegati o i caricamenti di byte firmati possono usare lo stesso percorso.

Dopo la preparazione, invia i byte dei file richiesti e chiama `complete_catalogue_upload` con lo stesso `requestId`. Apri la versione privata per provarla. Per un aggiornamento, leggi `list_games`, mantieni lo stesso `name`, indica una nuova `version` e l’istantanea completa, e imposta `expectedCurrentVersion[name]` sulla versione pubblica attuale restituita dal server (o su `null` se non ce n’è). È un controllo dei conflitti, non la versione che stai caricando. Riprova i caricamenti interrotti con il loro ID richiesta originale. Pubblica con `publish_game_version` la versione conservata e provata quando sei pronto.

## Esempio di compatibilità legacy per un singolo gioco

L’esempio qui sotto è la forma legacy per un singolo gioco. I caricamenti completi del catalogo supportano anche più giochi, asset, pacchetti e specifiche; chiedi al connettore lo schema attuale. Ogni aggiornamento fornisce un’istantanea completa con visibilità e versione esplicite. Le voci del catalogo omesse non vengono eliminate.

Mantieni stabile lo slug in minuscolo quando aggiorni. Aggiungi un titolo da mostrare, una descrizione accurata, i comandi, la lingua originale e i tag noti, se servono. L’esempio qui sotto usa il tag di genere platformer esistente.

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

## Campi supportati e limiti

`name`: da 1 a 100 lettere minuscole, cifre o trattini, che inizi con una lettera o una cifra. `displayName`: titolo non vuoto. `subtitle`: fino a 120 caratteri. `description`: fino a 3.000 caratteri di Markdown, senza titoli H1, contenuti incorporati o tabelle. `inspirationPrompt`: fino a 400 caratteri di testo semplice su una sola riga. I limiti di testo contano le unità di codice UTF-16 di JavaScript.

I campi facoltativi includono `controls`, `releaseNotes`, `makingOf`, `emoji`, `color`, `sourceRepository`, `license`, `tags`, `sourceLocale`, `listingLocalizations`, `listingMedia` e `server`. I tag usano riferimenti esistenti `group-slug/tag-slug`, con al massimo 20 tag univoci. `server` elenca le stanze Colyseus di un `server.js` caricato, per esempio `"server": { "rooms": ["game"] }`; vedi l’[SDK server](https://www.playdrop.ai/it/create/learn/server-sdk). Chiedi al connettore i valori di licenza accettati e le regole complete dei campi prima della pubblicazione. Suggerimenti facoltativi per le app native: `prefetch` elenca i file caricati che le app iOS, macOS e Android di PlayDrop possono scaricare prima di giocare, per esempio `"prefetch": { "required": ["game.js"], "optional": ["music.mp3"] }` (la pagina di ingresso è sempre inclusa), e `"offlineSupported": true` permette a quelle app di offrire il gioco offline una volta salvati i file richiesti. I valori non validi vengono ignorati e non bloccano mai un caricamento; i siti web caricano i giochi come al solito.

Giochi Instant: imposta `"instant": true` quando il gioco è giocabile entro 2 secondi da al massimo 10 MB di file di avvio (la pagina di ingresso più `prefetch.required`, oppure tutti i file caricati se non ne sono elencati). I giochi Instant hanno il badge a forma di fulmine e si giocano nel feed Instant delle app per telefono di PlayDrop. Metti livelli più avanzati ed extra in `prefetch.optional`, completa la compilazione degli shader e altri preparativi prima di chiamare `ready()`, fai in modo che l’anteprima mostri il gameplay e non una schermata del titolo, e consenti gli ospiti (`authMode` `OPTIONAL` o `NONE`) così tutti vedono il gioco nel feed. PlayDrop controlla le dimensioni al caricamento e toglie il badge alle versioni che sui telefoni partono lentamente; un gioco che non raggiunge la soglia viene comunque pubblicato.

## Immagini e video della scheda

Carica i contenuti della scheda come file accanto a `index.html`, nominati dal percorso: `listing/icon.png`, `listing/hero-landscape.png` (16:9) e `listing/hero-portrait.png` (9:16) con il titolo del gioco nell’immagine, screenshot come `listing/screenshots/landscape/0.png` e video `listing/videos/landscape/0.mp4` (il trailer) e `listing/videos/portrait/0.mp4` (il teaser per mobile). I video si riproducono senza audio sulle carte dei giochi e sulla pagina del gioco, il trailer su computer e TV e il teaser su telefono, quindi sono il modo più rapido per mostrare il gameplay e conquistare una prima partita. Le immagini sono PNG e i video MP4.

## Traduci la scheda con precisione

Pubblica sempre l’inglese più la tua lingua quando è diversa. Imposta `sourceLocale` sulla lingua originale. `listingLocalizations` supporta inglese, francese, tedesco, spagnolo, portoghese brasiliano, indonesiano, giapponese, coreano, cinese tradizionale e cinese semplificato. Ogni traduzione richiede `locale` e `displayName`; quando la carichi con la sua fonte, PlayDrop compila `sourceHash`. Carica la grafica tradotta in `listing/locales/<locale>/`, per esempio `listing/locales/fr/hero-landscape.png` con il titolo in francese; viene associata automaticamente alla sua traduzione. Aggiorna le traduzioni dopo le modifiche alla fonte. Tradurre la scheda non traduce il gioco stesso.

## Giocatori, gruppi e controller

Dichiara come si gioca il tuo gioco con `types`, `party`, `controller` e `roomVoice` in ogni voce di gioco:

```json
{
  "types": ["solo", "online", "party"],
  "party": { "local": [1, 2, 3, 4], "online": [1, 2, 3, 4] },
  "controller": { "support": "optional", "type": "simpler" },
  "roomVoice": true
}
```

`types` combina `solo` (si gioca da soli), `online` (si gioca con altri in rete) e `party` (un gruppo che gioca insieme). `party.local` elenca i numeri esatti di persone che possono giocare su un solo schermo; `party.online` elenca le dimensioni dei gruppi di amici, fino a 4, che possono entrare online insieme, non la capacità della stanza. Le dimensioni sono esatte: `[2, 4]` esclude 3. `party` richiede il tipo `party`, `party.online` richiede `online` e un 1 in `party.local` richiede `solo`. `roomVoice: true` attiva la voce di stanza e richiede `online`.

`controller.support` è `off` (il valore predefinito quando `controller` è omesso), `optional` o `required`. Quando non è `off`, `controller.type` indica i comandi minimi di cui il gioco ha bisogno:

- `any`: direzioni, Conferma e Annulla; funziona qualsiasi controller, inclusi i telecomandi.
- `simpler`: uno stick analogico, quattro pulsanti frontali e Menu; vanno bene i controller su telefono di PlayDrop e i gamepad standard.
- `standard`: croce direzionale, due stick cliccabili, quattro pulsanti frontali, due pulsanti dorsali, due grilletti e Menu.
- `custom`: riservato ai comandi su telefono specifici del gioco; non ancora disponibile.

Con il supporto ai controller attivo, ogni numero locale dichiarato deve essere giocabile con i controller; leggi l’input dei controller tramite l’[SDK](https://www.playdrop.ai/it/create/learn/sdk). I giochi esistenti possono mantenere `players` e `controllerMode`, che continuano a funzionare, ma i nuovi giochi usano questi campi, e una voce non può mescolare entrambi. L’host seleziona il gioco locale o online, mai entrambi. Queste dichiarazioni sopravvivono ai caricamenti da Cloud, CLI e MCP, alle versioni private conservate e alla pubblicazione. La disponibilità dipende anche dal rollout della piattaforma e dalla build dell’host.

Per i caricamenti del server MCP, fornisci un bundle ESM `.mjs`/`.js` compilato come descrittore `SERVER` e punta `server.entry` a quel file. I progetti sorgente per Cloud/CLI mantengono il loro entry TypeScript. PlayDrop fornisce il runtime di Colyseus e dell’SDK server; non includere mai in un gioco le credenziali del provider vocale.