適用於瀏覽器遊戲的 PlayDrop 用戶端 SDK
適用於任何 PlayDrop 遊戲的選用瀏覽器 SDK：只需一個 script 標籤，即可使用主機端生命週期、登入、存檔、排行榜、購買、廣告、好友、控制器、多人連線與共用程式庫。
PlayDrop SDK 是選用的：沒有使用 SDK 的遊戲同樣能在 PlayDrop 上遊玩。若需要平台功能，例如玩家登入、存檔、成就與排行榜、以點數購買、廣告、PlayDrop Chat 中的好友與遊戲卡片、分享連結、由主機端管理的暫停與音訊、控制器輸入、託管多人連線以及 AI 生成，就加入 SDK。PlayDrop Cloud 會為你完成整合；使用 PlayDrop Connector 時，你的代理只需加入一個 script 標籤。
加入 SDK 並遵循主機端生命週期
<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>從 PlayDrop 的 CDN 載入 SDK，不需要安裝任何套件。在呼叫 sdk.host.ready() 之前，先渲染第一個可遊玩的畫面並準備好輸入。主機端暫停時請暫停模擬，恢復時不要產生重複的迴圈，並遵循主機端的音訊政策。
身分、存檔與語言
sdk.me 提供玩家身分，sdk.me.appData 儲存私人存檔；sdk.achievements 與 sdk.leaderboards 負責成就與分數。存檔、成就與排行榜無需事先檢查登入狀態即可運作。對於需要真實帳號的功能（例如購買或多人連線），請使用 sdk.me.isLoggedIn。預覽與擷取模式不得寫入玩家進度。sdk.host.language 提供玩家的語言：請提供英文版本，若你的語言不是英文，也一併提供。翻譯上架資訊並不會翻譯遊戲內容。在獲勝等自然停頓時，sdk.host.requestReview() 會讓 PlayDrop 請玩家評價（每款遊戲最多一次）；遊戲永遠不會知道答案，所以絕不要為評價提供獎勵。
程式庫、素材與多人連線
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/，即可在真正的 PlayDrop 框架中搭配 SDK 主機端遊玩。任何 localhost 連接埠或 https 網址都適用。需要帳號的功能（例如存檔與購買）在遊戲上傳過一次後即可運作；私人上傳就足夠了。瀏覽器端的媒體生成以非同步任務執行，並需經主機端確認點數費用。上架中繼資料請參閱 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 }] })。這些提示只影響音量和聲像，不影響授權。伺服器負責實施隊伍和距離條件。
使用 sdk.device.localPlayers 和 sdk.device.onLocalPlayersChange(callback) 取得選定的本機控制器插槽 { playerIndex, gamepadKey }。已連接控制器清單是獨立的；中斷連線的插槽仍保留其識別資訊。本機模式不能加入線上房間。可複製的 playdrop-metagame/recipes/play-together 範例展示兩種模式、兩個目的地和房間政策。
控制器
在所有平台上都透過 sdk.device 以相同方式讀取實體控制器和 PlayDrop 手機控制器。在 init() 之後呼叫一次 enableControllerInput()，在遊戲迴圈中讀取 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();不要呼叫 navigator.getGamepads()：手機控制器只能透過 SDK 傳給遊戲，遊戲直接讀取瀏覽器 API 時 PlayDrop 會記錄警告。如果主機端無法提供控制器輸入，enableControllerInput() 會以 controller_input_unavailable 或 controller_input_timeout 拒絕，遊戲會繼續執行。pad.has("dpad") 可判斷某個操控是否存在；請在 catalogue.json 中宣告遊戲所需的操控。