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@mnouzcatalogue.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
{
"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
| Field | Rules |
|---|---|
name | Required 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 |
file | Entry page path; defaults to <name>.html |
version | Semantic version, new for each upload of the game |
visibility | PUBLIC, UNLISTED or PRIVATE; see who can play |
releaseNotes | What changed in this version: one line of 1–240 characters |
license | CLOSED, PLAYDROP or MIT |
sourceRepository | Optional public source link |
Listing text
| Field | Rules |
|---|---|
displayName | Required title |
subtitle | Aim for 4–8 words and about 60 characters; 120 maximum |
description | Up to 3,000 characters of Markdown, without H1 headings, embedded media or tables |
controls | How to play, in one or two sentences |
inspirationPrompt | Up to 400 characters of single-line plain text |
makingOf | How the game was made |
emoji, color | A symbol and a #RRGGBB accent color |
tags, design | Required 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
| Field | Rules |
|---|---|
types | Required: any of solo, online, party |
party.local | Exact player counts on one screen; 1 requires solo |
party.online | Exact arriving group sizes up to 4; requires online |
async.friend | Use [2] for a saved two-player match that friends can start from a DM and resume from a turn card. Requires online. |
controller | Required support: off, optional or required; type: any, simpler or standard |
roomVoice | true enables room voice; requires online |
players, controllerMode | Older 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
| Field | Rules |
|---|---|
surfaceTargets | Object with desktop, mobileLandscape, mobilePortrait booleans; at least one, all tested |
primarySurface | DESKTOP, MOBILE_LANDSCAPE or MOBILE_PORTRAIT |
authMode | REQUIRED (default), OPTIONAL (guests and accounts) or NONE (no sign-in) |
instant | Claim Instant eligibility |
prefetch | { required: [...], optional: [...] } files the apps download before or after start |
offlineSupported | true lets the apps offer the game offline |
previewable, editorSupported | The game handles the preview phase; it ships a game-owned Editor |
tweaks | Creator-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,scoreTypewithsort(INTEGER+DESCorTIME_MS+ASC), optionalunitLabelandstatus.achievements[]:key,displayName,description,kind(STANDARDorINCREMENTALwithmaxProgress),icon(PNG path), optionalhiddenandstatus.
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
| Field | Rules |
|---|---|
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.






