# 適用於瀏覽器遊戲的 PlayDrop 用戶端 SDK

適用於任何 PlayDrop 遊戲的選用瀏覽器 SDK：只需一個 script 標籤，即可使用主機端生命週期、登入、存檔、排行榜、購買、廣告、好友、多人連線與共用程式庫。

Source: https://www.playdrop.ai/zh-hant/docs/sdk

PlayDrop SDK 是選用的：沒有使用 SDK 的遊戲同樣能在 PlayDrop 上遊玩。若需要平台功能，例如玩家登入、存檔、成就與排行榜、以點數購買、廣告、PlayDrop Chat 中的好友與遊戲卡片、分享連結、由主機端管理的暫停與音訊、託管多人連線以及 AI 生成，就加入 SDK。[PlayDrop Cloud](https://www.playdrop.ai/zh-hant/create) 會為你完成整合；使用 [PlayDrop Connector](https://www.playdrop.ai/zh-hant/docs/connectors) 時，你的代理只需加入一個 script 標籤。

## 加入 SDK 並遵循主機端生命週期

從 PlayDrop 的 CDN 載入 SDK，不需要安裝任何套件。在呼叫 `sdk.host.ready()` 之前，先渲染第一個可遊玩的畫面並準備好輸入。主機端暫停時請暫停模擬，恢復時不要產生重複的迴圈，並遵循主機端的音訊政策。

```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.me` 提供玩家身分，`sdk.me.appData` 儲存私人存檔；`sdk.achievements` 與 `sdk.leaderboards` 負責成就與分數。存檔、成就與排行榜無需事先檢查登入狀態即可運作。對於需要真實帳號的功能（例如購買或多人連線），請使用 `sdk.me.isLoggedIn`。預覽與擷取模式不得寫入玩家進度。`sdk.host.locale` 提供玩家的語言：請提供英文版本，若你的語言不是英文，也一併提供。翻譯上架資訊並不會翻譯遊戲內容。

## 程式庫、素材與多人連線

`sdk.libs` 可載入支援的 Three.js、Phaser、Rapier、nipplejs 與 Colyseus 版本。`sdk.assets` 提供目錄、素材包與素材參照；`sdk.social` 提供好友、遊戲卡片與分享操作。在託管多人連線中，`sdk.multiplayer.getConnection()` 會回傳伺服器位址與已登入玩家的權杖；請使用 Colyseus 用戶端加入。[伺服器 SDK](https://www.playdrop.ai/zh-hant/docs/server-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](https://www.playdrop.ai/zh-hant/docs/catalogue-json)。