PlayDrop game servers: Colyseus, MongoDB and the server SDK
Optional hosted multiplayer for PlayDrop games: upload a Colyseus server.js with MongoDB storage, test it with Test Players, and use the optional server SDK for friends and AI.
A game server is optional. Your game can call any server you run yourself. If you prefer, PlayDrop hosts a standard Colyseus server with a MongoDB database for your game: upload it as server.js next to index.html through PlayDrop Connector, or ask PlayDrop Cloud to build it. The @playdrop/server package is optional too.
Write a standard Colyseus server
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) };Export a rooms map from server.js and list its room names in catalogue.json as "server": { "rooms": ["game"] }. PlayDrop runs the server, so do not start one yourself. Store data with the standard MongoDB driver through PLAYDROP_MONGO_URL, inside the room lifecycle.
Hosted server rules
- Colyseus 0.17 (
colyseus0.17.10,@colyseus/schema4.0.30), the MongoDB driver 7.5 and Node 22. - One self-contained ES module of up to 2 MiB. It may import only
colyseus,@colyseus/core,@colyseus/schema,mongodband@playdrop/server; bundle any other code into the file. - Up to 2 room types, 8 players per room, 4 hours per room, 30 messages per second per player and 512 KiB per message.
- No internet access from the server: only MongoDB and PlayDrop services are reachable.
- Players must be signed in. PlayDrop verifies each player when they join; do not implement
onAuth. - One MongoDB database per game, kept across versions and counted in your storage quota. Never send its credentials to the browser.
Connect the browser and test
In the browser, sdk.multiplayer.getConnection() from the client SDK returns the server address and the player's token; join with the Colyseus client (@colyseus/sdk 0.17). During development, run Colyseus 0.17 and MongoDB 8 locally and connect to your local server directly. To test the hosted server, upload a private version, then open https://www.playdrop.ai/create/games/<slug>/test?v=<version>&player=1 and the same link with player=2 in a second window: each window plays as a separate test account. Make the version public from the game page when it works.
Optional server SDK: friends and AI
@playdrop/server adds playdrop.social (friends playing this game and game cards in PlayDrop Chat) and playdrop.ai (text, image, 3D, video, sound, speech and music generation paid by the creator). These calls work on uploaded games only, not in local development. Download private generated media on the server with playdrop.ai.tasks.downloadFile and send the bytes only to the intended player; speech requests accept at most 40 words.
Party and room voice
await playdrop.social.getParty(client.auth) reads currently authorized party membership. It does not expose party chat or other-game activity, and does not grant party management. Existing social APIs keep their behavior.
A catalogue declaring roomVoice: true starts with an all-room policy; no server call is needed for that default. To customize it, bind const platform = playdrop.multiplayer.forRoom(this) to the actual Colyseus room. Use platform.voice.setPolicy("all" | "team" | "proximity" | "off", { range: 20 }), setTeam(client.auth, teamId), setAudience(client.auth, audience) and updatePositions([{ player: client.auth, position: { x, y, z } }]). Pass null to clear a team or player override. Proximity needs fresh authoritative positions.
The trusted runtime coalesces eligibility changes, reserves accepted party followers after the leader's ordinary join, and cleans up permissions. Games never send audio, provider credentials or microphone requests. Keep the same room across rounds. Use the existing private Test Players with an eligible creator to test the integration before publishing; publication alone does not enable the rollout.