# PlayDrop 遊戲中的線上派對與語音聊天

讓朋友一起線上玩你的遊戲：宣告派對人數、開啟 PlayDrop 的派對視窗、用 sdk.multiplayer.join 加入預留的房間，並控制房間語音。

Source: https://www.playdrop.ai/zh-hant/create/learn/online-party

PlayDrop 派對是一群一起在遊戲之間移動的朋友。當派對啟動你的遊戲時，PlayDrop 會在你伺服器的某個房間中為成員預留座位，讓朋友進入同一場對戰，而不會被拆散。語音聊天在 PlayDrop 中執行，而不是在你的遊戲中。

## 你需要什麼

- 一個[即時遊戲伺服器](https://www.playdrop.ai/zh-hant/create/learn/game-servers)：派對在你的 Colyseus 房間中遊玩。
- 已登入的玩家：房間會拒絕訪客。
- [catalogue.json](https://www.playdrop.ai/zh-hant/create/learn/catalogue-json) 中的這些宣告：

```json
{
  "types": ["solo", "online", "party"],
  "party": { "online": [2, 3, 4] },
  "roomVoice": true,
  "server": { "entry": "server/index.mjs", "rooms": ["game"] }
}
```

`party.online` 列出可以一同加入的確切群組人數，最多 4 人；`[2, 4]` 會排除 3 人。這是一同加入的群組人數，不是房間容量：兩個四人派對可以共用一個八人房間。`party` 需要 `party` 類型，`party.online` 需要 `online`。`roomVoice: true` 會啟用房間語音，並需要 `online`。

## 加入正確的房間

```js
if (!sdk.me.isLoggedIn) {
  await sdk.me.promptLogin();
}
const room = await sdk.multiplayer.join("game", { mode: "versus" });
```

PlayDrop 啟動派對時，`join` 會使用玩家預留的派對座位，否則就獨立加入。若以派對身分加入失敗，呼叫會以錯誤拒絕；絕不會悄悄把玩家放進其他房間。訪客會收到 `authentication_required`，PlayDrop 會顯示登入畫面；請從 `sdk.me.onAuthChange` 再次加入。各回合之間請保留同一個房間。

重新載入後，`sdk.multiplayer.reconnect(roomName, token)` 會用你為這款遊戲、版本和使用者私下儲存的重新連線權杖，恢復預留的座位。遇到 `multiplayer_reconnect_expired`、`multiplayer_reconnect_unavailable` 或 `party_reconnect_mismatch` 時，請捨棄權杖並呼叫 `join`。

## 派對視窗

從按鈕呼叫 `sdk.social.openParty({ mode: "online" })`，會開啟 PlayDrop 的派對視窗，玩家可以在其中邀請朋友，以及開啟或關閉語音。現有的派對會被沿用。`openParty()` 會開啟派對選單，`openParty({ section: "voice" })` 會開啟語音設定；不要同時使用 `mode` 和 `section`。視窗關閉時 promise 就會完成，包括取消的情況。

用 `sdk.social.getParty()` 或 `sdk.social.onPartyChange(callback)` 讀取派對，後者會先傳送目前的狀態：`{ partyId, leaderUserId, revision, members, launch }`。派對正在玩這款遊戲時，`launch.status` 為 `joining` 或 `ready`。光是同屬一個派對，不代表玩家共用同一個房間；請使用 `join`。

派對成員由 PlayDrop 管理：遊戲無法新增或移除派對成員，也無法控制麥克風，玩家要從這個視窗邀請朋友加入派對。遊戲仍可以用 `sdk.social.sendMessage` 傳送自己的邀請或挑戰卡片給朋友；請參閱[分享、好友與邀請](https://www.playdrop.ai/zh-hant/create/learn/social)。

## 房間語音

設定 `roomVoice: true` 後，房間裡的每個人都能交談，不需要伺服器程式碼。若要改變誰能聽到誰，請在你的伺服器上綁定房間並設定語音規則：

```js
import { playdrop } from "@playdrop/server";

const platform = playdrop.multiplayer.forRoom(this);
platform.voice.setPolicy("team");
platform.voice.setTeam(client.auth, "red");
```

規則有 `all`、`team`、`proximity`（附 `{ range }`）和 `off`。`setAudience(player, audience)` 可覆寫單一玩家的設定，`updatePositions([{ player, position: { x, y, z } }])` 則提供距離資料；傳入 `null` 可清除分隊或覆寫設定。PlayDrop 會強制執行誰能聽到誰。在瀏覽器中，`sdk.multiplayer.voice.updateSpatialState({ listener: { position, forward, up }, speakers: [{ userId, position }] })` 只會調整音量和聲像。

語音受玩家同意、靜音和封鎖的限制，也取決於主機端的建置版本與開放進度。

## 暫停

派對膠囊不會暫停遊戲。PlayDrop 的暫停會停止你的用戶端，但房間會保持連線，你的伺服器也會繼續執行。一位玩家暫停，絕不能讓其他人的對戰停下來；任何對戰暫停都請在伺服器上實作。

## 測試

上傳私人版本，然後在兩個視窗中以 `player=1` 和 `player=2` 開啟測試連結，如[即時遊戲伺服器](https://www.playdrop.ai/zh-hant/create/learn/game-servers)中所述。使用控制器的本機派對是另一種模式：請參閱[本機派對與控制器](https://www.playdrop.ai/zh-hant/create/learn/local-party)。

## 相關指南

- [即時遊戲伺服器](https://www.playdrop.ai/zh-hant/create/learn/game-servers): 為你的遊戲執行附帶 MongoDB 資料庫的託管 Colyseus 0.17 伺服器，用 SDK 從瀏覽器連線，用兩位玩家測試，並了解各項限制。
- [本機派對與控制器](https://www.playdrop.ai/zh-hant/create/learn/local-party): 透過 sdk.device 讀取實體手把與 PlayDrop 手機控制器，追蹤本機玩家插槽，並宣告控制器支援與本機派對人數。
- [分享、好友與邀請](https://www.playdrop.ai/zh-hant/create/learn/social): 附圖片或短片分享遊戲、讀取啟動酬載、挑選好友、在 PlayDrop Chat 中傳送邀請與挑戰卡片，並推薦其他遊戲。