Reference
PlayDrop server SDK reference: Colyseus, MongoDB and @playdrop/server
Reference for PlayDrop-hosted game servers: runtime rules, the verified PlayDropPlayer, and the social, shop, ai and multiplayer server APIs.
Connect your AI app
Arrowbound@mnouzA hosted game server is a standard Colyseus 0.17 module that PlayDrop runs next to a MongoDB database for your game. @playdrop/server is an optional library for trusted platform calls from that server. The realtime game servers guide explains when to use one and how to test it. Exact parameter and return types, generated from the server SDK's source, are in the server SDK declarations and the shared types they use. AI apps read them with get_documentation topics server-sdk-types and shared-types.
Module shape
import { Room, defineRoom } from "colyseus";
import { playdrop } from "@playdrop/server";
class GameRoom extends Room {
async onJoin(client) {
const friends = await playdrop.social.listGameFriends(client.auth);
client.send("friends", friends.map((friend) => friend.username));
}
}
export const rooms = { game: defineRoom(GameRoom) };Declare the module in catalogue.json with "server": { "entry": "server/index.mjs", "rooms": ["game"] }. PlayDrop authenticates every player before onJoin: do not define onAuth or start a server yourself.
Runtime rules
| Rule | Value |
|---|---|
| Runtime | Node.js 24.22.1, colyseus 0.17.10, @colyseus/schema 4.0.30, mongodb 7.5 |
| Bundle | One self-contained ES module, at most 2 MiB |
| Allowed imports | colyseus, @colyseus/core, @colyseus/schema, mongodb, @playdrop/server |
| Rooms | At most 2 room types; 8 players and 4 hours per room |
| Messages | 30 per second per player, 512 KiB each |
| Network | MongoDB and PlayDrop services only |
| Players | Signed in |
| Database | process.env.PLAYDROP_MONGO_URL, one per game, kept across versions; connect inside the room lifecycle |
client.auth: PlayDropPlayer
| Field | Meaning |
|---|---|
userId, username | The verified player; use userId for membership and storage |
appId, appVersionId | This game and version (0 for an unpublished draft) |
appRole | OWNER for the game's creator, otherwise PLAYER |
isTestPlayer, testSlot | Creator test players 1–4 |
sessionId | The PlayDrop play session, not the Colyseus session |
partyPlay, roomVoice | Set by PlayDrop for party launches and voice-enabled games |
Pass client.auth itself to the calls below; never build one from client messages.
playdrop.social
| Method | Purpose |
|---|---|
getParty(player) | The player's current party for this game, or null |
listGameFriends(player) | Friends with a recent session in this game |
sendMessage(player, input) | Send a game card from player (same input as the client SDK) |
getMessages(player, options?), consumeMessage(player, id) | Read and settle the player's cards |
playdrop.shop
| Method | Purpose |
|---|---|
verifyReceipt(player, receiptId, expected?) | Read and check a receipt owned by player for this game, without changing it |
consumeReceipt(player, receiptId, expected?) | Atomically settle an AUTHORIZED consumable before paid work |
cancelReceipt(player, receiptId, expected?) | Release the held credits when delivery is aborted |
refund(receiptId, { reason, player? }) | Refund a CONSUMED receipt when paid work fails for good: the credits return to the buyer. A repeat call changes nothing; within 7 days of the purchase |
expected checks sku, amount, kind and status. Bind each receipt ID to one delivery in MongoDB before consuming it. See monetization.
playdrop.ai
playdrop.ai.text, json, image, music, sfx, speech, video and model3d each have createTask(request, { owner? }). playdrop.ai.tasks has get(id), list(options?), events(id) and downloadFile(id, { role? }); playdrop.ai.inputs.upload(bytes, { fileName, contentType }) uploads a reference file. The creator pays and owns results unless owner names an eligible player. Speech accepts at most 40 words. See AI asset generation.
playdrop.multiplayer
playdrop.multiplayer.forRoom(room).voice controls room voice: setPolicy("all" | "team" | "proximity" | "off", { range? }), setTeam(player, team | null), setAudience(player, audience | null) and updatePositions([{ player, position }]). A game with roomVoice: true starts with all.
Errors
Server SDK calls reject with an Error whose message is a stable code, such as server_ai_invalid_request. They only work on uploaded games: in local development, use your own stand-ins. Never send database credentials, grants or test-player tokens to a browser.






