catalogue.json：PlayDrop 游戏元数据与本地化
PlayDrop Connector 格式的参考，涵盖游戏标题、描述、类型标签、商店页面图片和视频、翻译以及可选的 server 字段。
PlayDrop Connector 会将 catalogue.json 元数据与游戏文件一起发送，无需命令行工具。Studio 游戏的元数据由 PlayDrop Cloud 管理。
使用 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>"
}
]
}这是新私有游戏的完整 prepare_catalogue_upload 请求。将示例 HTML 替换为构建好的游戏，每次计划上传时使用唯一的 requestId。catalogue 对象是 catalogue.json 的内容；files 和 expectedCurrentVersion 属于工具请求，位于该对象之外。
apps[].file 必须与某个 files[].path 完全一致。如果省略 file，默认路径为 <name>.html，而不是 index.html。surfaceTargets 是包含 desktop、mobileLandscape 和 mobilePortrait 布尔值的对象；请至少启用一种经过测试的显示环境。明确声明版本和可见性。示例使用内联文本；附件或签名上传也可以使用同一路径。
准备完成后，发送所需文件，并使用同一 requestId 调用 complete_catalogue_upload。打开私有版本进行测试。更新时，读取 list_games，保留相同的 name，提供新的 version 和完整快照，并将 expectedCurrentVersion[name] 设为服务器返回的当前公开版本；若不存在则设为 null。该字段用于冲突检查，并非正在上传的版本。使用原请求 ID 恢复中断的上传。准备就绪后，通过 publish_game_version 发布已保留并测试的版本。
旧版单游戏格式兼容示例
以下示例使用旧版单游戏格式。完整目录也支持多个游戏、资源、资源包和规范，请向连接器索取最新架构。每次更新都发送完整快照，并明确版本与可见性。省略目录项目不会删除它们。
更新时请保持小写 slug 不变。根据需要添加显示标题、准确的描述、操作方式、源语言和已知标签。下面的示例使用了现有的平台跳跃类型标签。
{
"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"]
}]
}支持的字段与限制
name：1–100 个小写字母、数字或连字符，必须以字母或数字开头。displayName：非空标题。subtitle：最多 120 个字符。description：最多 3,000 个字符的 Markdown，不得包含 H1 标题、嵌入媒体或表格。inspirationPrompt：最多 400 个字符的单行纯文本。文本长度限制按 JavaScript UTF-16 代码单元计算。
可选字段包括 controls、releaseNotes、makingOf、emoji、color、sourceRepository、license、tags、sourceLocale、listingLocalizations、listingMedia 和 server。标签使用现有的 group-slug/tag-slug 引用，最多 20 个不重复的标签。server 列出已上传 server.js 的 Colyseus 房间，例如 "server": { "rooms": ["game"] }；请参阅 服务器 SDK。发布前，请向连接器查询当前可接受的许可证值和完整的字段规则。原生应用的可选提示：prefetch 列出 PlayDrop iOS、macOS 和 Android 应用可以在游玩前下载的已上传文件，例如 "prefetch": { "required": ["game.js"], "optional": ["music.mp3"] }（入口页面始终包含在内）；"offlineSupported": true 允许这些应用在必需文件保存后离线提供游戏。无效的值会被忽略，绝不会阻止上传；网站照常加载游戏。
即玩游戏：当游戏能在 2 秒内以最多 10 MB 的启动文件（入口页面加上 prefetch.required，若未列出则为所有上传文件）开始游玩时，请设置 "instant": true。即玩游戏会带有闪电徽章，并在 PlayDrop 手机应用的即玩信息流中游玩。请将进阶关卡和额外内容放入 prefetch.optional，在调用 ready() 前完成着色器编译等准备工作，让预览显示游戏画面而不是标题画面，并允许访客（authMode 为 OPTIONAL 或 NONE），让所有人都能在信息流中看到游戏。PlayDrop 会在上传时检查大小，并移除手机启动缓慢的版本的徽章；未达标准的游戏仍会发布。
商店页面图片和视频
将商店页面媒体作为文件上传到 index.html 旁边，并按路径命名：画面中带有游戏标题的 listing/icon.png、listing/hero-landscape.png（16:9）和 listing/hero-portrait.png（9:16），listing/screenshots/landscape/0.png 等截图，以及视频 listing/videos/landscape/0.mp4（预告片）和 listing/videos/portrait/0.mp4（移动端短预告）。视频会在游戏卡片和游戏页面上静音播放，电脑和电视播放预告片，手机播放短预告，因此它们是展示玩法、赢得首次游玩的最快方式。图片为 PNG 格式，视频为 MP4 格式。
准确翻译商店页面
务必发布英语版本，如果你的语言不是英语，也一并发布。将 sourceLocale 设置为原始语言。listingLocalizations 支持英语、法语、德语、西班牙语、巴西葡萄牙语、印度尼西亚语、日语、韩语、繁体中文和简体中文。每个翻译都需要 locale 和 displayName；将翻译与源内容一起上传时，PlayDrop 会自动填写 sourceHash。将翻译后的图片上传到 listing/locales/<locale>/ 下，例如带有法语标题的 listing/locales/fr/hero-landscape.png；它会自动与对应的翻译匹配。源内容更改后，请更新翻译。商店页面翻译不会翻译游戏本身。
玩家、队伍和控制器
在每个游戏条目中使用 types、party、controller 和 roomVoice 声明游戏的玩法：
{
"types": ["solo", "online", "party"],
"party": { "local": [1, 2, 3, 4], "online": [1, 2, 3, 4] },
"controller": { "support": "optional", "type": "simpler" },
"roomVoice": true
}types 可组合 solo（可单人游玩）、online（通过网络与他人一起玩）和 party（一群人一起玩）。party.local 列出可在同一屏幕上游玩的确切人数；party.online 列出可一起进入在线游戏的好友队伍人数（最多 4 人），而不是房间容量。人数是精确的：[2, 4] 不包括 3。party 需要 party 类型，party.online 需要 online，party.local 中包含 1 时需要 solo。roomVoice: true 开启房间语音，并且需要 online。
controller.support 为 off（省略 controller 时的默认值）、optional 或 required。不为 off 时，用 controller.type 指定游戏所需的最低操控：
any：方向、确认和取消；所有控制器都可使用，包括遥控器。simpler：一个模拟摇杆、四个功能键和菜单键；PlayDrop 手机控制器和标准手柄均符合要求。standard：方向键、两个可按压摇杆、四个功能键、两个肩键、两个扳机键和菜单键。custom：为游戏专属的手机操控保留，暂不可用。
开启控制器支持后，声明的每个本地人数都必须能用控制器游玩；请通过 SDK 读取控制器输入。现有游戏可以继续使用 players 和 controllerMode，它们仍然有效，但新游戏应使用这些字段，且同一条目不能混用两种写法。宿主只选择本地或在线模式，不会同时启用。声明会保留在 Cloud、CLI 和 MCP 上传、留存的私有版本以及发布版本中。可用性还取决于平台开放范围和宿主版本。
通过 MCP 上传服务器时，请提供构建好的 ESM .mjs/.js 包作为 SERVER 描述项，并让 server.entry 指向它。Cloud/CLI 源码项目保留 TypeScript 入口。PlayDrop 提供 Colyseus 和服务器 SDK 运行时；切勿在游戏中包含语音提供商凭据。