技術リファレンス

ブラウザゲーム向け PlayDrop クライアント SDK

あらゆる PlayDrop ゲームで使える任意のブラウザ SDK：ホストのライフサイクル、サインイン、セーブデータ、リーダーボード、購入、広告、フレンド、コントローラー、マルチプレイヤー、共有ライブラリを script タグ 1 つで利用できます。

PlayDrop SDK の導入は任意です。SDK がなくても、ゲームは PlayDrop でプレイできます。プレイヤーのサインイン、セーブデータ、実績とリーダーボード、クレジットでの購入、広告、PlayDrop Chat でのフレンドとゲームカード、共有リンク、ホストが管理する一時停止とオーディオ、コントローラー入力、ホスト型マルチプレイヤー、AI 生成といったプラットフォーム機能を使うには、SDK を追加してください。PlayDrop Cloud では SDK が自動で統合されます。PlayDrop Connector を使う場合は、エージェントが script タグを 1 つ追加します。

SDK を追加し、ホストのライフサイクルに従う

html

<script src="https://assets.playdrop.ai/sdk/playdrop.js"></script>
<script type="module">
  const sdk = await playdrop.init();
  // Render the game and prepare input, then:
  sdk.host.ready();
  sdk.host.onPause(() => pauseGame());
  sdk.host.onResume(() => resumeGame());
  sdk.host.onAudioPolicyChange(({ enabled }) => setAudioEnabled(enabled));
</script>

SDK は PlayDrop の CDN から読み込みます。パッケージのインストールは不要です。sdk.host.ready() を呼び出す前に、最初のプレイ可能なフレームを描画し、入力を準備してください。ホストが一時停止したらシミュレーションを一時停止し、ループを重複させずに再開し、ホストのオーディオポリシーに従ってください。

ID、セーブデータ、言語

sdk.me はプレイヤーの ID を提供し、sdk.me.appData は非公開のセーブデータを保存します。sdk.achievements と sdk.leaderboards は実績とスコアを扱います。セーブ、実績、リーダーボードは、事前にログインを確認しなくても動作します。購入やマルチプレイヤーなど、実際のアカウントが必要な機能には sdk.me.isLoggedIn を使用してください。プレビューモードとキャプチャモードでは、プレイヤーの進行状況を書き込んではいけません。sdk.host.language でプレイヤーの言語を取得できます。英語に加えて、あなたの言語が英語と異なる場合はその言語でも提供してください。掲載情報を翻訳しても、ゲーム内のコンテンツは翻訳されません。勝利の後など区切りのよい場面で sdk.host.requestReview() を呼ぶと、PlayDrop がプレイヤーに評価を依頼します（各ゲームで最大 1 回）。ゲームは回答を知ることがないため、評価に報酬を付けないでください。

ライブラリ、アセット、マルチプレイヤー

sdk.libs は、サポートされているバージョンの Three.js、Phaser、Rapier、nipplejs、Colyseus を読み込みます。sdk.assets はカタログ、パック、アセットの参照を提供し、sdk.social はフレンド、ゲームカード、共有のアクションを提供します。ホスト型マルチプレイヤーでは、sdk.multiplayer.getConnection() がサーバーのアドレスとサインイン中のプレイヤーのトークンを返します。Colyseus クライアントで参加してください。ホスト型サーバーについてはサーバー SDK のページで説明しています。自前で運用するサーバーでは、SDK は必要ありません。旧来のリレールーム API は廃止されました。

公開前に SDK でテストする

いつもの開発サーバーを起動し、Chrome で https://www.playdrop.ai/creators/<username>/apps/game/<slug>/dev?url=http://localhost:5173/ を開くと、SDK ホストを備えた実際の PlayDrop フレーム内でプレイできます。localhost の任意のポートや https URL を使用できます。セーブデータや購入など、アカウントが必要な機能は、ゲームを一度アップロードすると動作します。非公開のアップロードで十分です。ブラウザでのメディア生成は、ホストが確認したクレジットコストを伴う非同期タスクとして実行されます。掲載情報のメタデータについては、catalogue.json を参照してください。

一緒に遊ぶ

プレイ中に await sdk.multiplayer.join("game") を使うと、個別にルームへ参加するか、ホストのパーティー予約を利用できます。パーティーの参加に失敗した場合、プレイヤーを別のルームへ分けずに要求を拒否します。既存ゲームでは getConnection() で引き続き接続情報を即座に取得できます。ラウンド間で同じルームを維持し、ホストの画面がゲーム入力を一時停止しても通信を続けてください。

プレイヤーの操作から sdk.social.openParty() を呼び出すと、ホストのパーティー画面が開きます。メンバーは await sdk.social.getParty() または sdk.social.onPartyChange(callback) で確認できます。ゲームはプラットフォームのパーティーを変更したり、マイクを制御したりできません。音声はウェブまたはネイティブのホストが管理し、同意、ミュート、ブロック、提供対象の条件に従います。

滑らかな空間音声には、有限値の { x, y, z } ベクトルで sdk.multiplayer.voice.updateSpatialState({ listener: { position, forward, up }, speakers: [{ userId, position }] }) を呼び出します。ヒントは音量と左右の定位にのみ影響し、権限には影響しません。チームと近接条件はサーバーが適用します。

選択されたローカルコントローラーのスロット { playerIndex, gamepadKey } は sdk.device.localPlayers と sdk.device.onLocalPlayersChange(callback) で取得します。接続済みコントローラーの一覧は別で、切断されたスロットも識別情報を保持します。ローカルモードではオンラインルームに参加できません。コピー可能な playdrop-metagame/recipes/play-together レシピには、両モード、2つの移動先、ルームポリシーの例があります。

コントローラー

物理コントローラーと PlayDrop のスマホコントローラーは、どのプラットフォームでも同じように sdk.device で読み取ります。init() の後に enableControllerInput() を1回呼び出し、ゲームループで gamepad(playerIndex) を読み取り（0 が P1）、ボタンの押下と解放には onButton を使います。軸とボタンはブラウザの標準ゲームパッドの順序に従います。ボタンには south や east などの位置による名前があり、pad.label("south") はそのコントローラーでの表示名（"A" や "Cross" など）を返します。メニューボタンは PlayDrop が使用し、ゲームを一時停止します。

await sdk.device.enableControllerInput();
const stop = sdk.device.onButton(({ playerIndex, button, pressed }) => {
  if (button === "south" && pressed) jump(playerIndex);
});
function update() {
  const pad = sdk.device.gamepad(0);
  if (pad?.connected) move(pad.axes[0], pad.axes[1]);
  requestAnimationFrame(update);
}
update();

スマホコントローラーは SDK を通じてのみゲームに届き、ゲームがブラウザ API を直接読み取ると PlayDrop は警告を記録するため、navigator.getGamepads() は呼び出さないでください。ホストがコントローラー入力を提供できない場合、enableControllerInput() は controller_input_unavailable または controller_input_timeout で拒否され、ゲームはそのまま動作し続けます。pad.has("dpad") で操作系の有無を確認できます。ゲームに必要な操作系は catalogue.json で宣言してください。