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.
PlayDrop Connector 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
{
"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>"
}
]
}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.
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.
{
"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. 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:
{
"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. 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.