一起玩

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

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

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

你需要什麼

一個即時遊戲伺服器：派對在你的 Colyseus 房間中遊玩。
已登入的玩家：房間會拒絕訪客。
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。

加入正確的房間

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 傳送自己的邀請或挑戰卡片給朋友；請參閱分享、好友與邀請。

房間語音

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

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 開啟測試連結，如即時遊戲伺服器中所述。使用控制器的本機派對是另一種模式：請參閱本機派對與控制器。

一起玩