PlayDrop logoPlayDrop Studio
CreatePlayTradeEarnLearnConnectorsAssetsCommunitySupport
PlayDrop logoPlayDrop Studio
CreatePlayTradeEarnLearnConnectorsAssetsCommunitySupport
Sign in
Server SDK
Documentation

Start here

OverviewYour first gamePlayDrop gamesAI game makers comparedFAQ

Create with Cloud

Cloud creationPlans & generations

Connect your AI app

All connectorsClaudeChatGPTClaude CodeCodexCursorGeminiAntigravityGrok BuildGrok BotGrok ChatLovableReplit

Publish and share

Publish from your AI appShare a ChatGPT gameShare a Claude gamePublish a browser gameSimple HTML gamesPackaging and .playPublish & importGame filesVisibility and reachListing art and videoGenres and tagsLocalizationInstant games

Game experience

Loading, pause and audioFull screen and safe areasCloud savesLocal parties and controllers

Play together

Sharing, friends and invitesLeaderboardsAchievementsOnline parties and voiceRealtime game servers

Earn

MonetizationCredits & rewards

Assets

Game assetsAI asset generationCustom formats and player creations

Reference

Client SDKServer SDKcatalogue.jsonErrors and recoveryTroubleshooting
DocumentationServer SDK

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@mnouz

A 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

js
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

RuleValue
RuntimeNode.js 24.22.1, colyseus 0.17.10, @colyseus/schema 4.0.30, mongodb 7.5
BundleOne self-contained ES module, at most 2 MiB
Allowed importscolyseus, @colyseus/core, @colyseus/schema, mongodb, @playdrop/server
RoomsAt most 2 room types; 8 players and 4 hours per room
Messages30 per second per player, 512 KiB each
NetworkMongoDB and PlayDrop services only
PlayersSigned in
Databaseprocess.env.PLAYDROP_MONGO_URL, one per game, kept across versions; connect inside the room lifecycle

client.auth: PlayDropPlayer

FieldMeaning
userId, usernameThe verified player; use userId for membership and storage
appId, appVersionIdThis game and version (0 for an unpublished draft)
appRoleOWNER for the game's creator, otherwise PLAYER
isTestPlayer, testSlotCreator test players 1–4
sessionIdThe PlayDrop play session, not the Colyseus session
partyPlay, roomVoiceSet 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

MethodPurpose
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

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

Related guides

  • Realtime game serversRun a hosted Colyseus 0.17 server with a MongoDB database for your game, connect from the browser with the SDK, test with two players and know the limits.
  • Online parties and voiceLet friends play together online: declare party sizes, open PlayDrop's party window, join reserved rooms with sdk.multiplayer.join and control room voice.
  • Client SDKReference for the PlayDrop browser SDK: host lifecycle, identity and saves, controllers, social, multiplayer, shop, ads, leaderboards, assets and AI.

Real games on PlayDrop

  • Voxel Vice@olivier
  • Prompt Pursuit@olivier
  • Pals vs Zombies@olivier
  • Hollow Havoc@mnouz
  • Stellar Leap@mnouz
  • Rainbow Rabbit Run@newagekid52

Make games people want to play.

Create a gameConnect your AI app
PreviousPlayDrop client SDK referenceNextcatalogue.json reference for PlayDrop games
View Markdown
EnglishFrançaisDeutsch日本語한국어EspañolPortuguês (Brasil)Bahasa Indonesia繁體中文简体中文ItalianoPolskiNederlandsSvenskaNorsk bokmålSuomiTürkçeไทยTiếng Việtالعربية

On this page

Module shapeRuntime rulesclient.auth: PlayDropPlayerplaydrop.socialplaydrop.shopplaydrop.aiplaydrop.multiplayerErrors
View Markdown