# PlayDrop 上的实时游戏服务器：Colyseus 和 MongoDB

为你的游戏运行托管的 Colyseus 0.17 服务器和 MongoDB 数据库，用 SDK 从浏览器连接，用两位玩家测试，并了解各项限制。

Source: https://www.playdrop.ai/zh-hans/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` 只在运行时存在。请为你的查询创建索引。

## 声明服务器

把服务器打包成一个文件，并在 catalogue 中指向它：

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

用[包](https://www.playdrop.ai/zh-hans/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-hans/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-hans/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-hans/create/learn/online-party): 让朋友们在线一起玩你的游戏：声明队伍人数，打开 PlayDrop 的队伍窗口，用 sdk.multiplayer.join 加入预留的房间，并控制房间语音。
- [服务器 SDK](https://www.playdrop.ai/zh-hans/create/learn/server-sdk): PlayDrop 托管游戏服务器参考：运行环境规则、经过验证的 PlayDropPlayer，以及 playdrop.social、playdrop.shop、playdrop.ai 和 playdrop.multiplayer。
- [打包和 .play](https://www.playdrop.ai/zh-hans/create/learn/packaging): 整理一个根目录带有 catalogue.json 的已构建游戏文件夹、ZIP 或 .play，声明商店页面媒体和服务器，并用 prepare_catalogue_upload 上传。