Reference
PlayDrop client SDK reference
Reference for the PlayDrop browser SDK: host lifecycle, identity and saves, controllers, social, multiplayer, shop, ads, leaderboards, assets and AI.
Connect your AI app
Arrowbound@mnouzThe client SDK connects a browser game to PlayDrop's host on the website and in the apps. This page is a map of its namespaces; the linked guides explain when and how to use each one. The exact parameter and return types of every method, generated from the SDK's source declarations, are in the client SDK declarations and the shared types they use. AI apps read them with get_documentation topics sdk-types and shared-types.
Load and initialize
<script src="https://assets.playdrop.ai/sdk/playdrop.js"></script>
<script type="module">
const sdk = await playdrop.init();
// Read sdk.host state, subscribe, render the first frame, then:
sdk.host.ready();
</script>playdrop.init() resolves once with the SDK object below. Using the SDK requires a package; the simple HTML path refuses it. TypeScript declarations come with the playdrop-sdk-types package.
sdk.host
| Member | Purpose |
|---|---|
ready(), error(message?), editorReady() | Signal the first playable frame, a fatal start error, or a ready game-owned Editor |
phase, onPhaseChange(cb) | preview, play or editor |
mode, deployment, platform, sdkVersion | dev/play, dev/live, web/native, SDK version |
isPaused, onPause(cb), onResume(cb) | Host pause with a reason |
audioAllowed, onAudioAllowedChange(cb), audioEnabled, onAudioPolicyChange(cb) | Whether the game may play sound |
reservedCorners, onReservedCornersChange(cb) | Host controls over the top corners, in CSS pixels |
language, locale | Player language (20 languages; locale limited to the original 10) |
share(options) | Share the game's page with text, payload, image or video |
launchPayload, launchFriend | Data from a shared link or card (read it first); the friend whose direct chat opened the game |
showGames({ games }), preloadGame(ref) | Recommend 1–3 other games; hint the next one |
requestReview() | Let PlayDrop ask for a review at a natural break |
Guides: lifecycle, viewport, sharing, localization.
sdk.me
| Member | Purpose |
|---|---|
isLoggedIn, userId, username | The real PlayDrop account, if any |
login(), promptLogin({ reason }), onAuthChange(cb) | Ask the host to sign the player in, saying why; follow changes |
appData, updateAppData(data) | Cloud save snapshot and full-object write |
selectedProfileAssetRef, getSelectedProfileAssetRef() | The player's avatar asset |
Games with authMode: "NONE" cannot ask for sign-in. Guide: cloud saves.
sdk.leaderboards and sdk.achievements
| Member | Purpose |
|---|---|
leaderboards.list(options?), get(key, { top, aroundMe }), submitScore(key, score) | Declared boards, ranks and best scores |
achievements.list(options?), get(key), unlock(key), setProgressAtLeast(key, total) | Declared achievements and progress |
Guides: leaderboards, achievements.
sdk.device and sdk.haptics
| Member | Purpose |
|---|---|
category, orientation, inputs | desktop/tablet/phone, orientation, keyboard/mouse/touch |
enableControllerInput(), gamepad(playerIndex), onButton(cb) | Physical and phone controllers |
localPlayers, onLocalPlayersChange(cb) | Local party slots |
controllerAvailability, connectedGamepads, onControllerChange(cb) | Controller inventory |
haptics.supported, selection(), impact(style?), notification(type) | Native vibration feedback |
Guide: local parties and controllers.
sdk.social
| Member | Purpose |
|---|---|
selectFriends({ max }), listGameFriends() | Pick friends; friends who play this game |
sendMessage(input), getMessages(options?), consumeMessage(id) | Game cards in PlayDrop Chat |
openProfile(userId), openChat({ recipientUserId, draftMessage }) | Host profile and chat windows |
openParty(options?), getParty(), onPartyChange(cb) | Party window and membership |
Guides: sharing, friends and invites, online parties.
sdk.multiplayer and sdk.connection
| Member | Purpose |
|---|---|
multiplayer.join(roomName, options?) | Join a room of the game's server, using party seats when present |
multiplayer.reconnect(roomName, token) | Restore a reserved seat after a reload |
multiplayer.getConnection() | { endpoint, token, expiresAt } for a raw Colyseus client |
multiplayer.voice.updateSpatialState(state) | Room voice volume and panning hints |
connection.getStatus(), getQuality(), serverNow(), renderTime(), onStatusChange(cb), onQualityChange(cb) | Compatibility clocks for older games; networking uses the Colyseus room |
Guide: realtime game servers.
sdk.shop and sdk.ads
| Member | Purpose |
|---|---|
shop.purchase(payload) | Buy a consumable or entitlement with credits; resolves an AUTHORIZED receipt |
shop.consume(id), shop.grant(id), shop.cancel(id) | Settle or cancel a receipt |
shop.receipts(filters?), shop.onDevice | Restore purchases; offline-first host flag |
ads.interstitial.load(), show() | Interstitial ads |
ads.rewarded.load(), show() | Rewarded ads; reward only on completed |
Guide: monetization.
sdk.assets and sdk.search
| Member | Purpose |
|---|---|
assets.resolveAppAsset(runtimeKey), listAppAssets() | The game's declared assets and file URLs |
assets.catalog (listPublic, listForCreator, get, listVersions, downloadFile, …), assets.packs, assets.models, assets.specs, assets.graph | Browse, read and manage assets, packs, 3D models, specs and relations |
assets.custom.forSpec(ref) | Player creations in a custom format |
assets.tags.list(), tags.get(group, tag) | Discovery tags |
search.query(request) | Search creators, games, assets and packs |
Guides: game assets, custom formats, tags.
sdk.ai
ai.image, music, sfx, speech, video and model3d each have createTask(request) and generations(). ai.tasks has get, list, events, downloadFile, cancel and clear; ai.inputs.upload(blob) uploads a reference file. Media tasks ask the player to confirm a credit cost. ai.text and ai.json return app_ai_generation_disabled in hosted games; use the server SDK. Guide: AI asset generation.
sdk.libs, sdk.tweaks, sdk.creator and sdk.app
libs.three,phaser,rapier,nipplejs,colyseusandavatar:info()andload()return versions PlayDrop hosts and caches. Rapier's loader already initializes its WASM.tweaks.get()reads creator-tunable values declared in the catalogue.creatoris non-null only for the game's owner:replaceTweaks(values)andnotes(list,add,replace,remove) for playtest notes.appdescribes the running game:name,displayName,version,authMode,surfaceTargetsand more.
Errors and fallbacks
SDK calls reject with an Error whose message is a stable code, such as controller_input_timeout, host_share_video_unsupported or authentication_required. Keep the game playable when an optional service fails. Never call navigator.getGamepads(), bind Escape or the controller Menu button, or write progress outside the play phase. A readiness warning means an integration is missing; it does not prove the game behaves correctly, so test the uploaded game.






