catalogue.json : métadonnées et localisation des jeux PlayDrop
Référence pour les titres de jeux, les descriptions, les tags de genre, les images et vidéos de fiche, les traductions et le champ facultatif server, au format PlayDrop Connector.
PlayDrop Connector envoie les métadonnées catalogue.json avec les fichiers du jeu ; aucun outil en ligne de commande n’est nécessaire. PlayDrop Cloud gère ces métadonnées pour les jeux Studio.
Envoi privé complet avec 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>"
}
]
}Ceci est une requête prepare_catalogue_upload complète pour un nouveau jeu privé. Remplacez le HTML par votre jeu compilé et utilisez un requestId unique pour chaque envoi voulu. L’objet catalogue contient le fichier catalogue.json ; files et expectedCurrentVersion appartiennent à la requête de l’outil, en dehors de cet objet.
apps[].file doit correspondre exactement à un files[].path. Sans file, le chemin par défaut est <name>.html, pas index.html. surfaceTargets est un objet contenant les booléens desktop, mobileLandscape et mobilePortrait ; activez au moins une surface testée. Déclarez explicitement la version et la visibilité. L’exemple utilise du texte intégré ; les pièces jointes ou envois signés peuvent utiliser le même chemin.
Après la préparation, envoyez les fichiers demandés puis appelez complete_catalogue_upload avec le même requestId. Ouvrez la version privée pour la tester. Pour une mise à jour, consultez list_games, gardez le même name, fournissez une nouvelle version et l’instantané complet, puis définissez expectedCurrentVersion[name] sur la version publique actuelle renvoyée par le serveur, ou null si aucune n’existe. Ce champ vérifie les conflits ; ce n’est pas la version envoyée. Reprenez les envois interrompus avec leur identifiant de requête d’origine. Publiez la version conservée et testée avec publish_game_version lorsque vous êtes prêt.
Exemple de compatibilité avec l’ancien format à un jeu
L’exemple ci-dessous utilise l’ancien format pour un seul jeu. Les catalogues complets acceptent aussi plusieurs jeux, ressources, packs et spécifications ; demandez le schéma actuel au connecteur. Chaque mise à jour est un instantané complet avec version et visibilité explicites. Les éléments omis du catalogue ne sont pas supprimés.
Gardez le même slug en minuscules lors des mises à jour. Ajoutez selon vos besoins un titre d’affichage, une description précise, les commandes, la langue source et des tags connus. L’exemple ci-dessous utilise le tag de genre existant pour les jeux de plateforme.
{
"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"]
}]
}Champs pris en charge et limites
name : de 1 à 100 lettres minuscules, chiffres ou traits d’union, commençant par une lettre ou un chiffre. displayName : titre non vide. subtitle : jusqu’à 120 caractères. description : jusqu’à 3 000 caractères en Markdown, sans titres H1, médias intégrés ni tableaux. inspirationPrompt : jusqu’à 400 caractères de texte brut sur une seule ligne. Les limites de texte sont calculées en unités de code UTF-16 JavaScript.
Les champs facultatifs comprennent controls, releaseNotes, makingOf, emoji, color, sourceRepository, license, tags, sourceLocale, listingLocalizations, listingMedia et server. Les tags utilisent des références existantes au format group-slug/tag-slug, dans la limite de 20 tags uniques. server liste les salles Colyseus d’un fichier server.js envoyé, par exemple "server": { "rooms": ["game"] } ; consultez le SDK serveur. Avant la publication, demandez au connecteur les valeurs de licence actuellement acceptées et l’ensemble des règles applicables aux champs. Indications facultatives pour les apps natives : prefetch liste les fichiers envoyés que les apps PlayDrop pour iOS, macOS et Android peuvent télécharger avant de jouer, par exemple "prefetch": { "required": ["game.js"], "optional": ["music.mp3"] } (la page d’entrée est toujours incluse), et "offlineSupported": true permet à ces apps de proposer le jeu hors ligne une fois ses fichiers requis enregistrés. Les valeurs non valides sont ignorées et ne bloquent jamais un envoi ; les sites web chargent les jeux comme d’habitude.
Jeux instantanés : indiquez "instant": true quand le jeu est jouable en moins de 2 secondes avec au plus 10 Mo de fichiers de démarrage (la page d’entrée plus prefetch.required, ou tous les fichiers envoyés si aucun n’est listé). Les jeux instantanés portent le badge éclair et se jouent dans le fil Instantané des apps mobiles PlayDrop. Placez les niveaux avancés et les extras dans prefetch.optional, terminez la compilation des shaders et tout préchargement avant d’appeler ready(), faites en sorte que l’aperçu montre le jeu plutôt qu’un écran titre, et acceptez les invités (authMode OPTIONAL ou NONE) pour que tout le monde voie le jeu dans le fil. PlayDrop vérifie la taille à l’envoi et retire le badge des versions que les téléphones lancent lentement ; un jeu qui n’atteint pas ce seuil est tout de même publié.
Images et vidéos de la fiche
Envoyez les médias de la fiche sous forme de fichiers placés à côté de index.html et nommés selon leur chemin : listing/icon.png, listing/hero-landscape.png (16:9) et listing/hero-portrait.png (9:16) avec le titre du jeu dans l’illustration, des captures d’écran comme listing/screenshots/landscape/0.png, ainsi que les vidéos listing/videos/landscape/0.mp4 (la bande-annonce) et listing/videos/portrait/0.mp4 (le teaser mobile). Les vidéos sont lues sans le son sur les cartes de jeu et sur la page du jeu, la bande-annonce sur ordinateur et TV et le teaser sur téléphone : c’est le moyen le plus rapide de montrer le gameplay et de décrocher une première partie. Les images sont au format PNG et les vidéos au format MP4.
Traduisez fidèlement la fiche
Publiez toujours la fiche en anglais, et aussi dans votre langue si elle est différente. Définissez sourceLocale sur la langue d’origine. listingLocalizations prend en charge l’anglais, le français, l’allemand, l’espagnol, le portugais du Brésil, l’indonésien, le japonais, le coréen, le chinois traditionnel et le chinois simplifié. Chaque traduction doit contenir locale et displayName ; lorsque vous l’envoyez avec sa source, PlayDrop renseigne sourceHash. Envoyez les illustrations traduites dans listing/locales/<locale>/, par exemple listing/locales/fr/hero-landscape.png avec le titre en français ; elles sont automatiquement associées à leur traduction. Actualisez les traductions après toute modification de la source. La traduction de la fiche ne traduit pas le jeu lui-même.
Joueurs, groupes et manettes
Déclarez comment votre jeu se joue avec types, party, controller et roomVoice dans chaque entrée de jeu :
{
"types": ["solo", "online", "party"],
"party": { "local": [1, 2, 3, 4], "online": [1, 2, 3, 4] },
"controller": { "support": "optional", "type": "simpler" },
"roomVoice": true
}types combine solo (jouable seul), online (avec d’autres joueurs en réseau) et party (un groupe qui joue ensemble). party.local liste le nombre exact de personnes pouvant jouer sur un même écran ; party.online liste les tailles de groupes d’amis, jusqu’à 4, qui peuvent entrer ensemble en ligne, pas la capacité de la salle. Les tailles sont exactes : [2, 4] exclut 3. party exige le type party, party.online exige online, et un 1 dans party.local exige solo. roomVoice: true active la voix de salle et exige online.
controller.support vaut off (par défaut quand controller est absent), optional ou required. S’il ne vaut pas off, controller.type indique les commandes minimales dont le jeu a besoin :
any: directions, Valider et Annuler ; toutes les manettes conviennent, télécommandes comprises.simpler: un stick analogique, quatre boutons d’action et Menu ; les manettes téléphone PlayDrop et les manettes standard conviennent.standard: croix directionnelle, deux sticks cliquables, quatre boutons d’action, deux boutons de tranche, deux gâchettes et Menu.custom: réservé aux commandes téléphone propres à un jeu ; pas encore disponible.
Avec la prise en charge des manettes, chaque nombre local déclaré doit être jouable avec des manettes ; lisez les manettes avec le SDK. Les jeux existants peuvent garder players et controllerMode, qui fonctionnent toujours, mais les nouveaux jeux utilisent ces champs, et une entrée ne peut pas mélanger les deux. L’hôte choisit le mode local ou en ligne, jamais les deux. Ces déclarations sont conservées dans les envois Cloud, CLI et MCP, les versions privées retenues et la publication. La disponibilité dépend aussi du déploiement de la plateforme et de la version de l’hôte.
Pour les serveurs envoyés via MCP, fournissez un bundle ESM compilé .mjs/.js comme descripteur SERVER et indiquez-le dans server.entry. Les projets sources Cloud/CLI conservent leur entrée TypeScript. PlayDrop fournit Colyseus et le runtime du SDK serveur ; n’incluez jamais d’identifiants de fournisseur vocal dans un jeu.