# catalogue.json: PlayDrops spelmetadata och lokalisering

Referens för speltitlar, beskrivningar, genretaggar, bilder och videor, översättningar och det valfria serverfältet i PlayDrop Connector-formatet.

Source: https://www.playdrop.ai/sv/create/learn/catalogue-json

[PlayDrop Connector](https://www.playdrop.ai/sv/create/connectors) skickar din `catalogue.json`-metadata tillsammans med spelfilerna. Inget kommandoradsverktyg behövs. PlayDrop Cloud underhåller den här metadatan för Studio-spel.

## Komplett privat uppladdning med prepare_catalogue_upload

Det här är en komplett `prepare_catalogue_upload`-förfrågan för ett nytt privat spel. Byt ut exempel-HTML-koden mot ditt byggda spel och använd ett unikt `requestId` för varje avsedd uppladdning. Objektet `catalogue` är innehållet i `catalogue.json`. `files` och `expectedCurrentVersion` hör till verktygsförfrågan, utanför det objektet.

```json
{
  "requestId": "my-game-v1-unique-request",
  "catalogue": {
    "apps": [
      {
        "name": "my-game",
        "displayName": "My Game",
        "file": "index.html",
        "version": "1.0.0",
        "visibility": "PRIVATE",
        "authMode": "OPTIONAL",
        "surfaceTargets": {
          "desktop": true,
          "mobileLandscape": false,
          "mobilePortrait": false
        }
      }
    ]
  },
  "expectedCurrentVersion": {
    "my-game": null
  },
  "files": [
    {
      "path": "index.html",
      "text": "<!doctype html><html><head><title>My Game</title></head><body><button onclick=\"this.textContent=Number(this.textContent)+1\">0</button></body></html>"
    }
  ]
}
```

`apps[].file` måste matcha en `files[].path` exakt. Om `file` utelämnas blir standardvärdet `<name>.html`, inte `index.html`. `surfaceTargets` är ett objekt med de booleska värdena `desktop`, `mobileLandscape` och `mobilePortrait`. Aktivera minst en yta som du har testat. Ange version och synlighet uttryckligen. Exemplet använder en inbäddad textfil. Bilagor eller signerade byteuppladdningar kan använda samma sökväg.

Efter förberedelsen skickar du de filbytes som efterfrågas och anropar `complete_catalogue_upload` med samma `requestId`. Öppna den privata versionen för att testa den. Vid en uppdatering läser du `list_games`, behåller samma `name`, anger en ny `version` och hela ögonblicksbilden och sätter `expectedCurrentVersion[name]` till den aktuella publika version som servern returnerar (eller `null` om det inte finns någon). Det är en konfliktkontroll, inte versionen som laddas upp. Försök igen med avbrutna uppladdningar med deras ursprungliga förfrågnings-ID. Publicera den testade, sparade versionen med `publish_game_version` när du är redo.

## Äldre kompatibilitetsexempel för ett enskilt spel

Exemplet nedan visar den äldre formen för ett enskilt spel. Fullständiga katalogöverföringar stöder också flera spel, assets, paket och specifikationer. Fråga connectorn efter det aktuella schemat. Varje uppdatering anger en fullständig ögonblicksbild med uttrycklig synlighet och version. Utelämnade katalogposter tas inte bort.

Behåll den gemena sluggen oförändrad vid uppdateringar. Lägg till en visningstitel, en korrekt beskrivning, kontroller, källspråket och kända taggar efter behov. Exemplet nedan använder den befintliga genretaggen för plattformsspel.

```json
{
  "apps": [{
    "name": "moon-jump",
    "displayName": "Moon Jump",
    "description": "Jump between lunar platforms and reach the finish.",
    "controls": "Arrow keys to move. Space to jump.",
    "sourceLocale": "en",
    "tags": ["game-genre/platformer"]
  }]
}
```

## Fält som stöds och gränser

`name`: 1–100 gemena bokstäver, siffror eller bindestreck, som börjar med en bokstav eller en siffra. `displayName`: en icke-tom titel. `subtitle`: upp till 120 tecken. `description`: upp till 3 000 tecken Markdown, utan H1-rubriker, inbäddad media eller tabeller. `inspirationPrompt`: upp till 400 tecken ren text på en rad. Textgränserna räknar JavaScripts UTF-16-kodenheter.

Valfria fält är bland annat `controls`, `releaseNotes`, `makingOf`, `emoji`, `color`, `sourceRepository`, `license`, `tags`, `sourceLocale`, `listingLocalizations`, `listingMedia` och `server`. Taggar använder befintliga referenser av formen `group-slug/tag-slug`, med högst 20 unika taggar. `server` listar Colyseus-rummen i en uppladdad `server.js`, till exempel `"server": { "rooms": ["game"] }`. Se [server-SDK:t](https://www.playdrop.ai/sv/create/learn/server-sdk). Fråga connectorn efter de licensvärden som för tillfället accepteras och de fullständiga fältreglerna före publicering. Valfria tips till native-appar: `prefetch` listar uppladdade filer som PlayDrops iOS-, macOS- och Android-appar kan ladda ned före spelet, till exempel `"prefetch": { "required": ["game.js"], "optional": ["music.mp3"] }` (startsidan ingår alltid), och `"offlineSupported": true` låter de apparna erbjuda spelet offline när de obligatoriska filerna är lagrade. Ogiltiga värden ignoreras och blockerar aldrig en uppladdning. Webbplatser läser in spel som vanligt.

Instant-spel: sätt `"instant": true` när spelet går att spela inom 2 sekunder från högst 10 MB startfiler (startsidan plus `prefetch.required`, eller alla uppladdade filer när inga är listade). Instant-spel får blixtmärket och spelas i Instant-flödet i PlayDrops telefonappar. Lägg djupare banor och extramaterial i `prefetch.optional`, gör klart kompilering av shaders och annan uppvärmning innan du anropar `ready()`, låt förhandsvisningen visa spelande i stället för en titelskärm och tillåt gäster (`authMode` `OPTIONAL` eller `NONE`) så att alla ser spelet i flödet. PlayDrop kontrollerar storleken vid uppladdning och tar bort märket från versioner som startar långsamt på telefoner. Ett spel som inte når upp till kravet publiceras ändå.

## Bilder och videor till spelsidan

Ladda upp media till spelsidan som filer bredvid `index.html`, namngivna efter sökväg: `listing/icon.png`, `listing/hero-landscape.png` (16:9) och `listing/hero-portrait.png` (9:16) med speltiteln i bilden, skärmdumpar som `listing/screenshots/landscape/0.png` samt videor `listing/videos/landscape/0.mp4` (trailern) och `listing/videos/portrait/0.mp4` (mobilteasern). Videor spelas utan ljud på spelkort och spelsidan, trailern på datorer och TV och teasern på telefoner, så de är det snabbaste sättet att visa spelandet och vinna en första spelomgång. Bilder är PNG och videor är MP4.

## Översätt spelsidan korrekt

Publicera alltid engelska plus ditt eget språk om det är ett annat. Sätt `sourceLocale` till originalspråket. `listingLocalizations` stöder engelska, franska, tyska, spanska, brasiliansk portugisiska, indonesiska, japanska, koreanska, traditionell kinesiska och förenklad kinesiska. Varje översättning behöver `locale` och `displayName`. När du laddar upp den med sin källa fyller PlayDrop i `sourceHash`. Ladda upp översatt grafik under `listing/locales/<locale>/`, till exempel `listing/locales/fr/hero-landscape.png` med den franska titeln. Den matchas automatiskt med sin översättning. Uppdatera översättningarna efter ändringar i källan. Översättning av spelsidan översätter inte själva spelet.

## Spelare, grupper och handkontroller

Ange hur spelet spelas med `types`, `party`, `controller` och `roomVoice` på varje spelpost:

```json
{
  "types": ["solo", "online", "party"],
  "party": { "local": [1, 2, 3, 4], "online": [1, 2, 3, 4] },
  "controller": { "support": "optional", "type": "simpler" },
  "roomVoice": true
}
```

`types` kombinerar `solo` (går att spela ensam), `online` (spelas med andra över nätverket) och `party` (en grupp som spelar tillsammans). `party.local` listar de exakta antalen personer som kan spela på en skärm. `party.online` listar de vängruppsstorlekar, upp till 4, som kan gå in online tillsammans, inte rummets kapacitet. Storlekarna är exakta: `[2, 4]` utesluter 3. `party` kräver typen `party`, `party.online` kräver `online` och en 1:a i `party.local` kräver `solo`. `roomVoice: true` slår på rumsröst och kräver `online`.

`controller.support` är `off` (standardvärdet när `controller` utelämnas), `optional` eller `required`. När det inte är `off` anger `controller.type` de minsta kontroller som spelet behöver:

- `any`: riktningar, Confirm och Cancel. Alla handkontroller fungerar, även fjärrkontroller.
- `simpler`: en analog spak, fyra frontknappar och Menu. PlayDrops telefonkontroller och vanliga gamepads uppfyller kravet.
- `standard`: riktningskors, två klickbara spakar, fyra frontknappar, två axelknappar, två avtryckare och Menu.
- `custom`: reserverad för spelspecifika telefonkontroller. Inte tillgänglig än.

Med handkontrollsstöd påslaget måste varje angivet lokalt antal gå att spela med handkontroller. Läs handkontrollsinmatning via [SDK:t](https://www.playdrop.ai/sv/create/learn/sdk). Befintliga spel kan behålla `players` och `controllerMode`, som fortfarande fungerar, men nya spel använder de här fälten, och en post kan inte blanda båda. Värden väljer lokalt eller onlinespel, aldrig båda. De här deklarationerna finns kvar vid uppladdningar via Cloud, CLI och MCP, i sparade privata versioner och vid publicering. Tillgängligheten beror också på plattformens utrullning och värdbygget.

Vid MCP-serveruppladdningar anger du ett byggt ESM-paket i `.mjs`/`.js` som en `SERVER`-beskrivning och pekar `server.entry` på det. Källprojekt för Cloud/CLI behåller sin TypeScript-startpunkt. PlayDrop tillhandahåller Colyseus och server-SDK:ts körmiljö. Ta aldrig med röstleverantörens inloggningsuppgifter i ett spel.