# PlayDrop 的即時遊戲伺服器：Colyseus 與 MongoDB

為你的遊戲執行附帶 MongoDB 資料庫的託管 Colyseus 0.17 伺服器，用 SDK 從瀏覽器連線，用兩位玩家測試，並了解各項限制。

Source: https://www.playdrop.ai/zh-hant/create/learn/game-servers

PlayDrop 可以託管遊戲的伺服器端：一個標準 Colyseus 伺服器，附帶專屬的 MongoDB 資料庫與經過驗證的玩家，不需要自行維運任何基礎架構。可用於即時對戰、回合制遊戲、共享世界，以及任何不能讓玩家作弊的內容。伺服器是選用的；你的遊戲也可以呼叫你自行架設的伺服器。

## 撰寫伺服器

從一個 ES 模組匯出 `rooms` 對照表。PlayDrop 會啟動伺服器；請勿呼叫 `listen()` 或定義 `onAuth`，因為 PlayDrop 會在 `onJoin` 之前驗證每位玩家。

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

class GameRoom extends Room {
  maxClients = 8;
  async onCreate() {
    this.mongo = new MongoClient(process.env.PLAYDROP_MONGO_URL);
    await this.mongo.connect();
    this.onMessage("move", (client, move) => this.applyMove(client.auth.userId, move));
  }
  onJoin(client) {
    // client.auth is the verified PlayDrop player: userId, username, appRole, isTestPlayer…
  }
  async onDispose() { await this.mongo?.close(); }
}

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

在房間生命週期內連線到 MongoDB，絕不要在模組範圍內連線：`PLAYDROP_MONGO_URL` 只在執行時存在。請為你的查詢建立索引。

## 宣告伺服器

將伺服器打包成一個檔案，並在目錄中指向它：

```json
{ "server": { "entry": "server/index.mjs", "rooms": ["game"] } }
```

請以[套件](https://www.playdrop.ai/zh-hant/create/learn/packaging)上傳；簡易 HTML 方式無法攜帶伺服器。

## 託管執行環境的規則

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

## 從瀏覽器連線

```js
const sdk = await playdrop.init();
const room = await sdk.multiplayer.join("game");
room.onStateChange((state) => render(state));
room.send("move", { x: 1 });
```

`join` 會處理 PlayDrop 的派對座位與登入；請參閱[線上派對](https://www.playdrop.ai/zh-hant/create/learn/online-party)。若需要更底層的控制，`sdk.multiplayer.getConnection()` 會傳回 `{ endpoint, token, expiresAt }`，供 `sdk.libs.colyseus.load()` 提供的官方 Colyseus 用戶端使用。

## 伺服器 SDK

`@playdrop/server` 加入受信任的平台呼叫：好友與遊戲卡片（`playdrop.social`）、購買驗證（`playdrop.shop`）、由創作者付費的 AI 生成（`playdrop.ai`），以及房間語音（`playdrop.multiplayer.forRoom`）。這些呼叫只適用於已上傳的遊戲。請參閱[伺服器 SDK 參考](https://www.playdrop.ai/zh-hant/create/learn/server-sdk)。

## 測試

開發期間，請在本機執行 Colyseus 0.17 與 MongoDB，並將本機用戶端連線到本機伺服器。若要測試託管伺服器，請上傳私人版本並開啟 `https://www.playdrop.ai/create/games/<slug>/test?v=<version>&player=1`，再於第二個視窗開啟改為 `player=2` 的同一連結。每個視窗都會以你名下不同的測試玩家身分遊玩。運作正常後，用 `publish_game_version` 發布已測試的版本。

為斷線做好設計：Colyseus 的重新連線會短暫保留座位，房間狀態應讓回來的玩家能繼續遊戲。

## 相關指南

- [線上派對與語音](https://www.playdrop.ai/zh-hant/create/learn/online-party): 讓朋友一起線上玩你的遊戲：宣告派對人數、開啟 PlayDrop 的派對視窗、用 sdk.multiplayer.join 加入預留的房間，並控制房間語音。
- [伺服器 SDK](https://www.playdrop.ai/zh-hant/create/learn/server-sdk): PlayDrop 託管遊戲伺服器參考：執行環境規則、經過驗證的 PlayDropPlayer，以及 playdrop.social、playdrop.shop、playdrop.ai 和 playdrop.multiplayer。
- [打包與 .play](https://www.playdrop.ai/zh-hant/create/learn/packaging): 安排根目錄含 catalogue.json 的建置遊戲資料夾、ZIP 或 .play，宣告上架媒體與伺服器，並用 prepare_catalogue_upload 上傳。