技術參考

PlayDrop 遊戲伺服器：Colyseus、MongoDB 與伺服器 SDK

PlayDrop 遊戲的選用託管多人連線：上傳使用 MongoDB 儲存的 Colyseus server.js，用測試玩家進行測試，並可選用伺服器 SDK 加入好友與 AI 功能。

遊戲伺服器是選用的。你的遊戲可以呼叫任何你自行架設的伺服器。若你偏好，PlayDrop 也能為你的遊戲託管一個附帶 MongoDB 資料庫的標準 Colyseus 伺服器：透過 PlayDrop Connector 將它以 server.js 上傳到 index.html 旁，或請 PlayDrop Cloud 為你打造。@playdrop/server 套件同樣是選用的。

撰寫標準 Colyseus 伺服器

import { Room, defineRoom } from "colyseus";
import { MongoClient } from "mongodb";

class GameRoom extends Room {
  async onCreate() {
    this.mongo = new MongoClient(process.env.PLAYDROP_MONGO_URL);
    await this.mongo.connect();
  }
  onJoin(client) {
    // client.auth is the verified PlayDrop player, for example client.auth.userId.
  }
  async onDispose() { await this.mongo?.close(); }
}

export const rooms = { game: defineRoom(GameRoom) };

從 server.js 匯出 rooms 對照表，並在 catalogue.json 中以 "server": { "rooms": ["game"] } 列出房間名稱。伺服器由 PlayDrop 執行，請勿自行啟動。在房間生命週期內，透過 PLAYDROP_MONGO_URL 使用標準 MongoDB 驅動程式儲存資料。

託管伺服器規則

Colyseus 0.17（colyseus 0.17.10、@colyseus/schema 4.0.30）、MongoDB 驅動程式 7.5 與 Node 22。
單一獨立完整的 ES 模組，最大 2 MiB。只能匯入 colyseus、@colyseus/core、@colyseus/schema、mongodb 與 @playdrop/server；其他程式碼請打包進該檔案。
最多 2 種房間類型、每個房間 8 名玩家、每個房間 4 小時、每位玩家每秒 30 則訊息，以及每則訊息 512 KiB。
伺服器無法存取網際網路：只能連線到 MongoDB 與 PlayDrop 服務。
玩家必須登入。PlayDrop 會在每位玩家加入時進行驗證；請勿實作 onAuth。
每款遊戲一個 MongoDB 資料庫，跨版本保留，並計入你的儲存空間配額。切勿將其憑證傳送到瀏覽器。

連接瀏覽器並測試

在瀏覽器中，用戶端 SDK 的 sdk.multiplayer.getConnection() 會回傳伺服器位址與玩家的權杖；請使用 Colyseus 用戶端（@colyseus/sdk 0.17）加入。開發期間，請在本機執行 Colyseus 0.17 與 MongoDB 8，並直接連線到本機伺服器。若要測試託管伺服器，請上傳私人版本，然後開啟 https://www.playdrop.ai/create/games/<slug>/test?v=<version>&player=1，並在第二個視窗開啟改為 player=2 的同一連結：每個視窗都會以不同的測試帳號遊玩。確認運作正常後，再從遊戲頁面將該版本設為公開。

選用的伺服器 SDK：好友與 AI

@playdrop/server 提供 playdrop.social（正在玩這款遊戲的好友，以及 PlayDrop Chat 中的遊戲卡片）與 playdrop.ai（由創作者付費的文字、圖片、3D、影片、音效、語音與音樂生成）。這些呼叫僅適用於已上傳的遊戲，無法在本機開發環境中使用。請在伺服器上使用 playdrop.ai.tasks.downloadFile 下載私人生成的媒體，並只將位元組傳送給預定的玩家；語音請求最多接受 40 個字詞。

隊伍與房間語音

await playdrop.social.getParty(client.auth) 讀取目前獲授權存取的隊伍成員資訊。它不會公開隊伍聊天或其他遊戲中的活動，也不會授予隊伍管理權限。現有社交 API 的行為保持不變。

在目錄中宣告 roomVoice: true 後，預設採用全房間語音政策；此預設設定不需要呼叫伺服器。如需自訂，請將 const platform = playdrop.multiplayer.forRoom(this) 綁定至實際的 Colyseus 房間。使用 platform.voice.setPolicy("all" | "team" | "proximity" | "off", { range: 20 })、setTeam(client.auth, teamId)、setAudience(client.auth, audience) 和 updatePositions([{ player: client.auth, position: { x, y, z } }])。傳入 null 可清除隊伍指派或玩家專屬的覆寫設定。近距離模式需要伺服器維護的最新權威位置資訊。

可信任的執行環境會合併資格變更，在隊長正常加入後為獲准跟隨的隊伍成員預留名額，並清理權限。遊戲絕不傳送音訊、供應商憑證或麥克風請求。請在不同回合之間保留同一個房間。發布前，請使用符合資格的創作者帳號與現有的私人 Test Players 測試整合；僅發布遊戲不會啟用此功能的分階段推出。

撰寫標準 Colyseus 伺服器

import { Room, defineRoom } from "colyseus";
import { MongoClient } from "mongodb";

class GameRoom extends Room {
  async onCreate() {
    this.mongo = new MongoClient(process.env.PLAYDROP_MONGO_URL);
    await this.mongo.connect();
  }
  onJoin(client) {
    // client.auth is the verified PlayDrop player, for example client.auth.userId.
  }
  async onDispose() { await this.mongo?.close(); }
}

export const rooms = { game: defineRoom(GameRoom) };

託管伺服器規則

Colyseus 0.17（colyseus 0.17.10、@colyseus/schema 4.0.30）、MongoDB 驅動程式 7.5 與 Node 22。
單一獨立完整的 ES 模組，最大 2 MiB。只能匯入 colyseus、@colyseus/core、@colyseus/schema、mongodb 與 @playdrop/server；其他程式碼請打包進該檔案。
最多 2 種房間類型、每個房間 8 名玩家、每個房間 4 小時、每位玩家每秒 30 則訊息，以及每則訊息 512 KiB。
伺服器無法存取網際網路：只能連線到 MongoDB 與 PlayDrop 服務。
玩家必須登入。PlayDrop 會在每位玩家加入時進行驗證；請勿實作 onAuth。
每款遊戲一個 MongoDB 資料庫，跨版本保留，並計入你的儲存空間配額。切勿將其憑證傳送到瀏覽器。

連接瀏覽器並測試

選用的伺服器 SDK：好友與 AI

隊伍與房間語音