PlayDrop logoPlayDrop Studio
CreatePlayTradeEarnLearnConnectorsAssetsCommunitySupport
PlayDrop logoPlayDrop Studio
CreatePlayTradeEarnLearnConnectorsAssetsCommunitySupport
Sign in
catalogue.json
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
Documentationcatalogue.json

Reference

catalogue.json reference for PlayDrop games

The catalogue.json fields PlayDrop games use: identity, listing, play modes, surfaces, sign-in, Instant, preloading, media, translations, scores and servers.

Connect your AI app
Arrowbound@mnouz

catalogue.json describes one or more games and their assets. It sits at the root of a package; your AI app sends it as the catalogue of prepare_catalogue_upload. PlayDrop Cloud writes it for Studio games. Text limits count JavaScript UTF-16 code units.

A complete app entry

json
{
  "apps": [{
    "name": "moon-jump",
    "displayName": "Moon Jump",
    "subtitle": "Lunar platform hopping against the clock",
    "description": "Jump between lunar platforms, collect oxygen and reach the flag.",
    "controls": "Tap or press Space to jump.",
    "file": "index.html",
    "version": "1.2.0",
    "visibility": "PUBLIC",
    "authMode": "OPTIONAL",
    "tags": ["game-genre/casual", "game-genre/platformer", "game-feel/relaxed"],
    "design": { "genre": "game-genre/platformer" },
    "types": ["solo"],
    "controller": { "support": "optional", "type": "simpler" },
    "surfaceTargets": { "desktop": true, "mobileLandscape": true, "mobilePortrait": true },
    "primarySurface": "MOBILE_PORTRAIT",
    "instant": true,
    "prefetch": { "required": ["game.js"], "optional": ["music.mp3"] },
    "sourceLocale": "en",
    "listing": { "icon": "listing/icon.png", "heroLandscape": "listing/hero-landscape.png", "heroPortrait": "listing/hero-portrait.png" },
    "leaderboards": [{ "key": "best-time", "displayName": "Best time", "description": "Fastest run", "scoreType": "TIME_MS", "sort": "ASC" }]
  }]
}

A catalogue may also contain assets, assetPacks and assetSpecs. There is no catalogue version field. The tables below cover the fields games use; an unknown or invalid field is refused with an error that names it.

Identity and version

FieldRules
nameRequired and permanent: 1–128 letters, digits, dots, underscores or hyphens. Use a short lowercase slug with hyphens, such as moon-jump; it becomes part of the game's address
fileEntry page path; defaults to <name>.html
versionSemantic version, new for each upload of the game
visibilityPUBLIC, UNLISTED or PRIVATE; see who can play
releaseNotesWhat changed in this version: one line of 1–240 characters
licenseCLOSED, PLAYDROP or MIT
sourceRepositoryOptional public source link

Listing text

FieldRules
displayNameRequired title
subtitleAim for 4–8 words and about 60 characters; 120 maximum
descriptionUp to 3,000 characters of Markdown, without H1 headings, embedded media or tables
controlsHow to play, in one or two sentences
inspirationPromptUp to 400 characters of single-line plain text
makingOfHow the game was made
emoji, colorA symbol and a #RRGGBB accent color
tags, designRequired genre and up to 20 tags; design names one tag per aspect: genre, coreGameplay, perspective, controls, visualStyle, progression, feel. See genres and tags

How it is played

FieldRules
typesRequired: any of solo, online, party
party.localExact player counts on one screen; 1 requires solo
party.onlineExact arriving group sizes up to 4; requires online
async.friendUse [2] for a saved two-player match that friends can start from a DM and resume from a turn card. Requires online.
controllerRequired support: off, optional or required; type: any, simpler or standard
roomVoicetrue enables room voice; requires online
players, controllerModeOlder fields that still work; never mix them with the fields above

party requires the party type. With controller support on, every local count must be playable with controllers. Guides: local parties, online parties.

Surfaces, sign-in and start

FieldRules
surfaceTargetsObject with desktop, mobileLandscape, mobilePortrait booleans; at least one, all tested
primarySurfaceDESKTOP, MOBILE_LANDSCAPE or MOBILE_PORTRAIT
authModeREQUIRED (default), OPTIONAL (guests and accounts) or NONE (no sign-in)
instantClaim Instant eligibility
prefetch{ required: [...], optional: [...] } files the apps download before or after start
offlineSupportedtrue lets the apps offer the game offline
previewable, editorSupportedThe game handles the preview phase; it ships a game-owned Editor
tweaksCreator-tunable values read with sdk.tweaks.get()

Invalid prefetch and offlineSupported values are ignored instead of blocking an upload.

Listing media and translations

listing holds icon, heroLandscape, heroPortrait, socialLandscape, and the arrays screenshotsLandscape, screenshotsPortrait, videosLandscape and videosPortrait. Images are PNG (social previews may be JPEG) and videos MP4. Array entries can be a path or { path, title, alt, caption }. Guide: listing art and video.

sourceLocale names the listing's language. listingLocalizations is an object keyed by language; each entry needs displayName and may hold subtitle, description, inspirationPrompt, controls, makingOf, releaseNotes and its own listing. Guide: localization.

Leaderboards and achievements

  • leaderboards[]: key, displayName, description, scoreType with sort (INTEGER+DESC or TIME_MS+ASC), optional unitLabel and status.
  • achievements[]: key, displayName, description, kind (STANDARD or INCREMENTAL with maxProgress), icon (PNG path), optional hidden and status.

Keys are 3–64 characters: a lowercase letter, then lowercase letters, digits, _, . or -. Keys cannot be removed and their type cannot change; set "status": "RETIRED" instead. Guides: leaderboards, achievements.

Assets and servers

FieldRules
ownedAssets[]Assets this game owns: name, runtimeKey, category, files (role → path), optional subcategory, format, visibility, license, tags, shopListed, shopPriceCredits
uses.assets[], uses.packs[]Published assets by exact revision (asset:creator/name@r3, optionally { ref, runtimeKey }) and packs by version (pack:creator/name@1.0.0)
assetSpecSupport[]{ assetSpec, versionRange, capabilities } for custom formats
server{ entry, rooms }: a built ES module and 1–2 lowercase room names

Guides: game assets, custom formats, game servers.

Updates

Each upload is a full snapshot of the app: fields you leave out are absent from the new version, so send everything again. Keep name unchanged, raise version, and preserve leaderboard and achievement keys. Catalogue items you leave out are not deleted.

Related guides

  • Packaging and .playLay out a built game folder, ZIP or .play with catalogue.json at its root, declare listing media and servers, and upload it with prepare_catalogue_upload.
  • Genres and tagsThe required genre, optional subgenre, play mode, theme and mood tags a PlayDrop game can use, and how they place a game in browsing and search.
  • Listing art and videoThe listing images and videos a PlayDrop game can have, their paths, formats and orientations, and how to make art that works in feeds, search and previews.

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 server SDK reference: Colyseus, MongoDB and @playdrop/serverNextPlayDrop MCP upload errors and how to recover
View Markdown
EnglishFrançaisDeutsch日本語한국어EspañolPortuguês (Brasil)Bahasa Indonesia繁體中文简体中文ItalianoPolskiNederlandsSvenskaNorsk bokmålSuomiTürkçeไทยTiếng Việtالعربية

On this page

A complete app entryIdentity and versionListing textHow it is playedSurfaces, sign-in and startListing media and translationsLeaderboards and achievementsAssets and serversUpdates
View Markdown