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（
colyseus0.17.10、@colyseus/schema4.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 测试集成；仅发布游戏不会启用此功能的分阶段推出。