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

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

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

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

## 撰寫標準 Colyseus 伺服器

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

```js
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](https://www.playdrop.ai/zh-hant/docs/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 個字詞。