catalogue.json: metadatos y localización de juegos de PlayDrop
Referencia sobre títulos de juegos, descripciones, etiquetas de género, imágenes y videos de la ficha, traducciones y el campo opcional server en el formato de PlayDrop Connector.
PlayDrop Connector envía los metadatos de catalogue.json junto con los archivos del juego; no necesitas una herramienta de línea de comandos. PlayDrop Cloud mantiene estos metadatos para los juegos de Studio.
Subida privada completa 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>"
}
]
}Esta es una solicitud prepare_catalogue_upload completa para un juego privado nuevo. Sustituye el HTML por tu juego compilado y usa un requestId único para cada subida prevista. El objeto catalogue contiene catalogue.json; files y expectedCurrentVersion pertenecen a la solicitud de la herramienta, fuera de ese objeto.
apps[].file debe coincidir exactamente con un files[].path. Si omites file, se usa <name>.html, no index.html. surfaceTargets es un objeto con los booleanos desktop, mobileLandscape y mobilePortrait; activa al menos una superficie que hayas probado. Declara la versión y la visibilidad explícitamente. El ejemplo usa texto integrado; los adjuntos o las subidas firmadas pueden usar la misma ruta.
Tras preparar la subida, envía los archivos solicitados y llama a complete_catalogue_upload con el mismo requestId. Abre la versión privada para probarla. Para actualizar, consulta list_games, conserva el mismo name, proporciona una nueva version y la instantánea completa, y fija expectedCurrentVersion[name] a la versión pública actual devuelta por el servidor, o null si no existe. Este campo comprueba conflictos; no es la versión que se sube. Recupera las subidas interrumpidas con su ID de solicitud original. Publica la versión conservada y probada con publish_game_version cuando esté lista.
Ejemplo de compatibilidad con el formato antiguo de un solo juego
El ejemplo siguiente usa el formato antiguo de un solo juego. Los catálogos completos también admiten varios juegos, recursos, packs y especificaciones; consulta el esquema actual al conector. Cada actualización envía una copia completa con versión y visibilidad explícitas. Omitir elementos del catálogo no los elimina.
Mantén estable el slug en minúsculas al actualizar. Añade según sea necesario un título visible, una descripción precisa, los controles, el idioma de origen y etiquetas conocidas. El ejemplo siguiente usa la etiqueta de género de plataformas existente.
{
"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"]
}]
}Campos admitidos y límites
name: 1–100 letras minúsculas, dígitos o guiones, empezando por una letra o un dígito. displayName: título no vacío. subtitle: hasta 120 caracteres. description: hasta 3,000 caracteres de Markdown, sin encabezados H1, contenido multimedia incrustado ni tablas. inspirationPrompt: hasta 400 caracteres de texto sin formato en una sola línea. Los límites de texto se cuentan en unidades de código UTF-16 de JavaScript.
Entre los campos opcionales se incluyen controls, releaseNotes, makingOf, emoji, color, sourceRepository, license, tags, sourceLocale, listingLocalizations, listingMedia y server. Las etiquetas usan referencias group-slug/tag-slug existentes, con un máximo de 20 etiquetas únicas. server enumera las salas de Colyseus de un server.js subido, por ejemplo "server": { "rooms": ["game"] }; consulta el SDK de servidor. Antes de publicar, pide al conector los valores de licencia aceptados actualmente y las reglas completas de los campos. Indicaciones opcionales para las apps nativas: prefetch enumera archivos subidos que las apps de PlayDrop para iOS, macOS y Android pueden descargar antes de jugar, por ejemplo "prefetch": { "required": ["game.js"], "optional": ["music.mp3"] } (la página de entrada siempre se incluye), y "offlineSupported": true permite que esas apps ofrezcan el juego sin conexión cuando sus archivos obligatorios estén guardados. Los valores no válidos se ignoran y nunca bloquean una subida; los sitios web cargan los juegos como siempre.
Juegos instantáneos: indica "instant": true cuando el juego se pueda jugar en menos de 2 segundos con un máximo de 10 MB de archivos de inicio (la página de entrada más prefetch.required, o todos los archivos subidos si no se indica ninguno). Los juegos instantáneos llevan la insignia del rayo y se juegan en el feed Instantáneo de las apps móviles de PlayDrop. Pon los niveles avanzados y los extras en prefetch.optional, termina la compilación de shaders y cualquier preparación antes de llamar a ready(), haz que la vista previa muestre el juego y no una pantalla de título, y permite invitados (authMode OPTIONAL o NONE) para que todos vean el juego en el feed. PlayDrop comprueba el tamaño al subirlo y quita la insignia a las versiones que los teléfonos inician despacio; un juego que no alcanza el umbral se publica igualmente.
Imágenes y videos de la ficha
Sube el contenido multimedia de la ficha como archivos junto a index.html, nombrados según su ruta: listing/icon.png, listing/hero-landscape.png (16:9) y listing/hero-portrait.png (9:16) con el título del juego en la ilustración, capturas de pantalla como listing/screenshots/landscape/0.png, y los videos listing/videos/landscape/0.mp4 (el tráiler) y listing/videos/portrait/0.mp4 (el teaser para móviles). Los videos se reproducen sin sonido en las tarjetas de juego y en la página del juego: el tráiler en ordenadores y TV, y el teaser en teléfonos. Son la forma más rápida de mostrar la jugabilidad y conseguir una primera partida. Las imágenes son PNG y los videos, MP4.
Traduce la ficha con precisión
Publica siempre en inglés y también en tu propio idioma si es distinto. Indica en sourceLocale el idioma original. listingLocalizations admite inglés, francés, alemán, español, portugués de Brasil, indonesio, japonés, coreano, chino tradicional y chino simplificado. Cada traducción necesita locale y displayName; cuando la subes junto con su contenido de origen, PlayDrop completa sourceHash. Sube las ilustraciones traducidas en listing/locales/<locale>/, por ejemplo listing/locales/fr/hero-landscape.png con el título en francés; se asocian automáticamente a su traducción. Actualiza las traducciones cuando cambie el contenido de origen. Traducir la ficha no traduce el juego en sí.
Jugadores, grupos y mandos
Declara cómo se juega tu juego con types, party, controller y roomVoice en cada entrada de juego:
{
"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 (se puede jugar en solitario), online (con otras personas por la red) y party (un grupo que juega junto). party.local indica el número exacto de personas que pueden jugar en una misma pantalla; party.online, los tamaños de grupo de amigos, hasta 4, que pueden entrar juntos en línea, no la capacidad de la sala. Los tamaños son exactos: [2, 4] excluye 3. party requiere el tipo party, party.online requiere online y un 1 en party.local requiere solo. roomVoice: true activa la voz de sala y requiere online.
controller.support es off (el valor predeterminado si se omite controller), optional o required. Si no es off, controller.type indica los controles mínimos que necesita el juego:
any: direcciones, Confirmar y Cancelar; funciona con cualquier mando, incluidos los mandos a distancia.simpler: un joystick analógico, cuatro botones frontales y Menú; los mandos de teléfono de PlayDrop y los gamepads estándar cumplen el requisito.standard: cruceta, dos joysticks pulsables, cuatro botones frontales, dos botones superiores, dos gatillos y Menú.custom: reservado para controles de teléfono propios de cada juego; aún no está disponible.
Con la compatibilidad con mandos activada, cada número local declarado debe poder jugarse con mandos; lee la entrada de los mandos con el SDK. Los juegos existentes pueden conservar players y controllerMode, que siguen funcionando, pero los juegos nuevos usan estos campos y una entrada no puede mezclar ambos. El anfitrión elige modo local o en línea, nunca ambos. Estas declaraciones se conservan en cargas Cloud, CLI y MCP, versiones privadas retenidas y publicación. La disponibilidad también depende del despliegue de la plataforma y la versión del anfitrión.
Para servidores cargados por MCP, proporciona un paquete ESM compilado .mjs/.js como descriptor SERVER y apúntalo en server.entry. Los proyectos fuente de Cloud/CLI conservan su entrada TypeScript. PlayDrop proporciona Colyseus y el entorno del SDK de servidor; nunca incluyas credenciales del proveedor de voz en un juego.