catalogue.json：PlayDrop ゲームのメタデータとローカライズ
ゲームのタイトル、説明、ジャンルタグ、掲載用の画像と動画、翻訳、任意の server フィールドについて、PlayDrop Connector のフォーマットで説明するリファレンスです。
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 の真偽値を持つオブジェクトです。テスト済みの表示環境を少なくとも1つ有効にしてください。バージョンと公開範囲は明示的に指定します。この例はインラインテキストを使っていますが、添付ファイルや署名付きアップロードでも同じパスを利用できます。
準備後に要求されたファイルを送信し、同じ requestId で complete_catalogue_upload を呼び出します。非公開バージョンを開いてテストしてください。更新時は list_games を読み、同じ name と新しい version、完全なスナップショットを指定します。expectedCurrentVersion[name] にはサーバーが返した現在の公開バージョンを設定し、存在しなければ null にします。これは競合確認用で、アップロードするバージョンではありません。中断したアップロードは元のリクエスト ID で再開します。準備ができたら、保持されたテスト済みバージョンを publish_game_version で公開します。
旧シングルゲーム形式の互換性サンプル
以下は従来の単一ゲーム形式の例です。完全なカタログでは複数のゲーム、アセット、パック、仕様も扱えます。最新スキーマはコネクタに確認してください。更新ごとに版と公開範囲を明示した完全なスナップショットを送ります。カタログから省略した項目は削除されません。
更新時は、小文字のスラッグを変更せずに維持してください。必要に応じて、表示タイトル、正確な説明、操作方法、元の言語、既知のタグを追加します。以下の例では、既存のプラットフォーマーのジャンルタグを使用しています。
{
"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 文字の 1 行のプレーンテキスト。テキストの長さの制限は、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 には、iOS、macOS、Android 版の PlayDrop アプリがプレイ前にダウンロードできるアップロード済みファイルを "prefetch": { "required": ["game.js"], "optional": ["music.mp3"] } のように記載します（エントリーページは常に含まれます）。"offlineSupported": true を指定すると、必須ファイルの保存後にこれらのアプリでゲームをオフラインで提供できます。無効な値は無視され、アップロードを妨げることはありません。ウェブサイトでは通常どおりゲームが読み込まれます。
インスタントゲーム：起動ファイル（エントリーページと prefetch.required、指定がない場合はアップロードしたすべてのファイル）が10 MB以内で、2秒以内に遊べる場合は "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（1人で遊べる）、online（ネットワーク越しに他の人と遊ぶ）、party（グループで一緒に遊ぶ）を組み合わせて指定します。party.local は1つの画面で遊べる正確な人数、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：アナログスティック1本、フェイスボタン4つ、メニュー。PlayDrop のスマホコントローラーと標準ゲームパッドが対応します。standard：十字キー、押し込み可能なスティック2本、フェイスボタン4つ、ショルダーボタン2つ、トリガー2つ、メニュー。custom：ゲーム専用のスマホ操作用に予約されています。まだ利用できません。
コントローラー対応を有効にした場合、宣言したすべてのローカル人数をコントローラーで遊べる必要があります。コントローラー入力は SDK で読み取ってください。既存のゲームは players と controllerMode を引き続き使えますが、新しいゲームはこれらのフィールドを使い、1つのエントリーで両方を混在させることはできません。ホストはローカルかオンラインのどちらかを選び、同時には使いません。宣言は Cloud、CLI、MCP のアップロード、保持された非公開バージョン、公開時にも維持されます。利用可否はプラットフォームの提供状況とホストのバージョンにも依存します。
MCP のサーバーアップロードには、ビルド済み ESM .mjs/.js バンドルを SERVER 記述子として用意し、server.entry で指定します。Cloud/CLI のソースプロジェクトは TypeScript のエントリーを保持します。Colyseus とサーバー SDK のランタイムは PlayDrop が提供します。音声プロバイダーの認証情報をゲームに含めないでください。