# 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.

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

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](https://www.playdrop.ai/docs/connectors), or ask [PlayDrop Cloud](https://www.playdrop.ai/create) to build it. The `@playdrop/server` package is optional too.

## Write a standard Colyseus server

Export a `rooms` map from `server.js` and list its room names in [catalogue.json](https://www.playdrop.ai/docs/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.

```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) };
```

## Hosted server rules

- Colyseus 0.17 (`colyseus` 0.17.10, `@colyseus/schema` 4.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`, `mongodb` and `@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](https://www.playdrop.ai/docs/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.