catalogue.json: metadados e localização de jogos no PlayDrop
Referência para títulos de jogos, descrições, tags de gênero, imagens e vídeos da listagem, traduções e o campo opcional de servidor no formato do PlayDrop Connector.
O PlayDrop Connector envia os metadados de catalogue.json junto com os arquivos do jogo; nenhuma ferramenta de linha de comando é necessária. O PlayDrop Cloud mantém esses metadados para jogos do Studio.
Envio privado completo com 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 é uma solicitação prepare_catalogue_upload completa para um novo jogo privado. Substitua o HTML pelo seu jogo compilado e use um requestId exclusivo para cada envio pretendido. O objeto catalogue contém o catalogue.json; files e expectedCurrentVersion pertencem à solicitação da ferramenta, fora desse objeto.
apps[].file deve corresponder exatamente a um files[].path. Sem file, o padrão é <name>.html, não index.html. surfaceTargets é um objeto com os booleanos desktop, mobileLandscape e mobilePortrait; ative pelo menos uma superfície testada. Declare a versão e a visibilidade explicitamente. O exemplo usa texto embutido; anexos ou envios assinados podem usar o mesmo caminho.
Após preparar, envie os arquivos solicitados e chame complete_catalogue_upload com o mesmo requestId. Abra a versão privada para testá-la. Para atualizar, consulte list_games, mantenha o mesmo name, forneça uma nova version e o retrato completo, e defina expectedCurrentVersion[name] como a versão pública atual retornada pelo servidor, ou null se não houver. Esse campo verifica conflitos; não é a versão enviada. Retome envios interrompidos com o ID de solicitação original. Publique a versão armazenada e testada com publish_game_version quando estiver pronta.
Exemplo de compatibilidade com o formato antigo de um único jogo
O exemplo abaixo usa o formato antigo de um único jogo. Catálogos completos também aceitam vários jogos, recursos, packs e especificações; peça o esquema atual ao conector. Cada atualização envia uma cópia completa com versão e visibilidade explícitas. Itens omitidos do catálogo não são excluídos.
Mantenha estável o slug em minúsculas ao atualizar. Adicione um título de exibição, uma descrição precisa, os controles, o idioma de origem e tags conhecidas, conforme necessário. O exemplo abaixo usa a tag existente do gênero plataforma.
{
"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 aceitos e limites
name: 1–100 letras minúsculas, dígitos ou hifens, começando com uma letra ou um dígito. displayName: título não vazio. subtitle: até 120 caracteres. description: até 3.000 caracteres de Markdown, sem títulos H1, mídia incorporada ou tabelas. inspirationPrompt: até 400 caracteres de texto simples em uma única linha. Os limites de texto contam unidades de código UTF-16 do JavaScript.
Os campos opcionais incluem controls, releaseNotes, makingOf, emoji, color, sourceRepository, license, tags, sourceLocale, listingLocalizations, listingMedia e server. As tags usam referências group-slug/tag-slug existentes, com no máximo 20 tags distintas. server lista as salas Colyseus de um server.js enviado, por exemplo "server": { "rooms": ["game"] }; consulte o SDK de servidor. Antes da publicação, peça ao conector os valores de licença aceitos atualmente e as regras completas dos campos. Dicas opcionais para os apps nativos: prefetch lista arquivos enviados que os apps do PlayDrop para iOS, macOS e Android podem baixar antes de jogar, por exemplo "prefetch": { "required": ["game.js"], "optional": ["music.mp3"] } (a página de entrada é sempre incluída), e "offlineSupported": true permite que esses apps ofereçam o jogo offline depois que os arquivos obrigatórios forem salvos. Valores inválidos são ignorados e nunca bloqueiam um envio; os sites carregam os jogos normalmente.
Jogos instantâneos: defina "instant": true quando o jogo puder ser jogado em até 2 segundos com no máximo 10 MB de arquivos de inicialização (a página de entrada mais prefetch.required, ou todos os arquivos enviados quando nenhum for listado). Jogos instantâneos têm o selo de raio e aparecem no feed Instantâneo dos apps de celular do PlayDrop. Coloque fases avançadas e extras em prefetch.optional, termine a compilação de shaders e qualquer preparação antes de chamar ready(), faça a prévia mostrar o jogo em vez de uma tela de título e permita convidados (authMode OPTIONAL ou NONE) para que todos vejam o jogo no feed. O PlayDrop verifica o tamanho no envio e remove o selo das versões que os celulares iniciam devagar; um jogo que não atinge o limite continua publicado.
Imagens e vídeos da listagem
Envie a mídia da listagem como arquivos ao lado do index.html, nomeados pelo caminho: listing/icon.png, listing/hero-landscape.png (16:9) e listing/hero-portrait.png (9:16), com o título do jogo na arte, capturas de tela como listing/screenshots/landscape/0.png e os vídeos listing/videos/landscape/0.mp4 (o trailer) e listing/videos/portrait/0.mp4 (o teaser para celular). Os vídeos são reproduzidos sem som nos cards de jogo e na página do jogo (o trailer em computadores e TVs, o teaser em celulares), por isso são a forma mais rápida de mostrar a jogabilidade e conquistar uma primeira partida. As imagens são PNG e os vídeos, MP4.
Traduza a listagem com precisão
Publique sempre em inglês e também no seu idioma, se for diferente. Defina sourceLocale como o idioma original. listingLocalizations aceita inglês, francês, alemão, espanhol, português do Brasil, indonésio, japonês, coreano, chinês tradicional e chinês simplificado. Cada tradução precisa de locale e displayName; quando você a envia junto com a origem, o PlayDrop preenche o sourceHash. Envie a arte traduzida em listing/locales/<locale>/, por exemplo listing/locales/fr/hero-landscape.png com o título em francês; ela é associada automaticamente à sua tradução. Atualize as traduções depois de alterações na origem. A tradução da listagem não traduz o jogo em si.
Jogadores, grupos e controles
Declare como o jogo é jogado com types, party, controller e roomVoice em cada entrada de jogo:
{
"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 (jogável sozinho), online (com outras pessoas pela rede) e party (um grupo jogando junto). party.local lista os números exatos de pessoas que podem jogar na mesma tela; party.online lista os tamanhos de grupos de amigos, até 4, que podem entrar juntos online, e não a capacidade da sala. Os tamanhos são exatos: [2, 4] exclui 3. party exige o tipo party, party.online exige online e um 1 em party.local exige solo. roomVoice: true ativa a voz da sala e exige online.
controller.support é off (o padrão quando controller é omitido), optional ou required. Quando não é off, controller.type indica os controles mínimos de que o jogo precisa:
any: direções, Confirmar e Cancelar; qualquer controle funciona, inclusive controles remotos.simpler: um analógico, quatro botões de ação e Menu; os controles de celular do PlayDrop e os gamepads padrão atendem.standard: direcional, dois analógicos clicáveis, quatro botões de ação, dois botões de ombro, dois gatilhos e Menu.custom: reservado para controles de celular específicos do jogo; ainda não disponível.
Com o suporte a controles ativado, todo número local declarado precisa ser jogável com controles; leia a entrada dos controles pelo SDK. Jogos existentes podem manter players e controllerMode, que continuam funcionando, mas jogos novos usam estes campos, e uma entrada não pode misturar os dois. O host escolhe local ou online, nunca ambos. As declarações permanecem em uploads Cloud, CLI e MCP, versões privadas retidas e publicação. A disponibilidade também depende da liberação na plataforma e da versão do host.
Para uploads de servidor por MCP, forneça um pacote ESM compilado .mjs/.js como descritor SERVER e indique-o em server.entry. Projetos-fonte Cloud/CLI mantêm a entrada TypeScript. O PlayDrop fornece Colyseus e o ambiente do SDK de servidor; nunca inclua credenciais de provedores de voz em um jogo.