# catalogue.json: spillmetadata og lokalisering på PlayDrop

Referanse for spilltitler, beskrivelser, sjangertagger, oppføringsbilder og -videoer, oversettelser og det valgfrie server-feltet i PlayDrop Connector-formatet.

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

[PlayDrop Connector](https://www.playdrop.ai/nb/create/connectors) sender `catalogue.json`-metadataene dine sammen med spillfilene. Du trenger ikke noe kommandolinjeverktøy. PlayDrop Cloud vedlikeholder disse metadataene for Studio-spill.

## Komplett privat opplasting med prepare_catalogue_upload

Dette er en komplett `prepare_catalogue_upload`-forespørsel for et nytt privat spill. Bytt ut eksempel-HTML-en med det ferdige spillet ditt, og bruk en unik `requestId` for hver tiltenkte opplasting. `catalogue`-objektet er innholdet i `catalogue.json`. `files` og `expectedCurrentVersion` hører til verktøyforespørselen, utenfor 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å samsvare nøyaktig med en `files[].path`. Hvis `file` utelates, er standarden `<name>.html`, ikke `index.html`. `surfaceTargets` er et objekt med de boolske verdiene `desktop`, `mobileLandscape` og `mobilePortrait`. Slå på minst én flate du har testet. Deklarer versjon og synlighet eksplisitt. Eksempelet bruker en innebygd tekstfil. Vedlegg eller signerte byte-opplastinger kan bruke samme sti.

Etter forberedelsen sender du de forespurte filbytene og kaller `complete_catalogue_upload` med samme `requestId`. Åpne den private versjonen for å teste den. For en oppdatering leser du `list_games`, beholder samme `name`, oppgir en ny `version` og hele øyeblikksbildet, og setter `expectedCurrentVersion[name]` til den gjeldende offentlige versjonen serveren returnerer (eller `null` hvis det ikke finnes noen). Det er en konfliktsjekk, ikke versjonen som lastes opp. Prøv avbrutte opplastinger på nytt med den opprinnelige forespørsels-ID-en. Publiser den testede, beholdte versjonen med `publish_game_version` når du er klar.

## Eksempel på eldre kompatibilitet for enkeltspill

Eksempelet nedenfor har den eldre formen for enkeltspill. Fullstendige katalogopplastinger støtter også flere spill, ressurser, pakker og spesifikasjoner. Be connectoren om gjeldende skjema. Hver oppdatering gir et fullstendig øyeblikksbilde med eksplisitt synlighet og versjon. Utelatte katalogelementer slettes ikke.

Hold slug-en med små bokstaver stabil ved oppdatering. Legg til en visningstittel, en nøyaktig beskrivelse, kontroller, kildespråket og kjente tagger etter behov. Eksempelet nedenfor bruker den eksisterende sjangertaggen for plattformspill.

```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"]
  }]
}
```

## Støttede felt og grenser

`name`: 1–100 små bokstaver, sifre eller bindestreker, som begynner med en bokstav eller et siffer. `displayName`: tittel som ikke er tom. `subtitle`: opptil 120 tegn. `description`: opptil 3000 tegn Markdown, uten H1-overskrifter, innebygde medier eller tabeller. `inspirationPrompt`: opptil 400 tegn ren tekst på én linje. Tekstgrensene teller JavaScript UTF-16-kodeenheter.

Valgfrie felt omfatter `controls`, `releaseNotes`, `makingOf`, `emoji`, `color`, `sourceRepository`, `license`, `tags`, `sourceLocale`, `listingLocalizations`, `listingMedia` og `server`. Tagger bruker eksisterende `group-slug/tag-slug`-referanser, med høyst 20 unike tagger. `server` lister Colyseus-rommene til en opplastet `server.js`, for eksempel `"server": { "rooms": ["game"] }`. Se [server-SDK-en](https://www.playdrop.ai/nb/create/learn/server-sdk). Be connectoren om gjeldende godkjente lisensverdier og fullstendige feltregler før publisering. Valgfrie hint til native apper: `prefetch` lister opplastede filer som PlayDrops iOS-, macOS- og Android-apper kan laste ned før spilling, for eksempel `"prefetch": { "required": ["game.js"], "optional": ["music.mp3"] }` (inngangssiden er alltid med), og `"offlineSupported": true` lar disse appene tilby spillet uten nett når de nødvendige filene er lagret. Ugyldige verdier ignoreres og blokkerer aldri en opplasting. Nettsteder laster spill som vanlig.

Instant-spill: sett `"instant": true` når spillet kan spilles innen 2 sekunder fra høyst 10 MB oppstartsfiler (inngangssiden pluss `prefetch.required`, eller alle opplastede filer når ingen er oppført). Instant-spill får lynmerket og spilles i Instant-feeden i PlayDrops telefonapper. Legg dypere brett og ekstra innhold i `prefetch.optional`, fullfør shader-kompilering og annen oppvarming før du kaller `ready()`, la forhåndsvisningen vise spilling i stedet for en tittelskjerm, og tillat gjester (`authMode` `OPTIONAL` eller `NONE`) slik at alle ser spillet i feeden. PlayDrop sjekker størrelsen ved opplasting og fjerner merket fra versjoner som starter sakte på telefoner. Et spill som ikke når kravet, blir likevel publisert.

## Oppføringsbilder og -videoer

Last opp oppføringsmedier som filer ved siden av `index.html`, navngitt etter sti: `listing/icon.png`, `listing/hero-landscape.png` (16:9) og `listing/hero-portrait.png` (9:16) med spilltittelen i grafikken, skjermbilder som `listing/screenshots/landscape/0.png`, og videoer `listing/videos/landscape/0.mp4` (traileren) og `listing/videos/portrait/0.mp4` (mobilteaseren). Videoer spilles lydløst på spillkort og på spillsiden, traileren på datamaskin og TV og teaseren på telefoner, så de er den raskeste måten å vise spillingen på og få en første spilløkt. Bilder er PNG og videoer MP4.

## Oversett oppføringen riktig

Publiser alltid engelsk pluss ditt eget språk hvis det er et annet. Sett `sourceLocale` til originalspråket. `listingLocalizations` støtter engelsk, fransk, tysk, spansk, brasiliansk portugisisk, indonesisk, japansk, koreansk, tradisjonell kinesisk og forenklet kinesisk. Hver oversettelse trenger `locale` og `displayName`. Når du laster den opp sammen med kilden, fyller PlayDrop ut `sourceHash`. Last opp oversatt grafikk under `listing/locales/<locale>/`, for eksempel `listing/locales/fr/hero-landscape.png` med den franske tittelen. Den kobles automatisk til oversettelsen sin. Oppdater oversettelser etter endringer i kilden. Oversettelse av oppføringen oversetter ikke selve spillet.

## Spillere, grupper og kontrollere

Deklarer hvordan spillet ditt spilles med `types`, `party`, `controller` og `roomVoice` på hver spilloppføring:

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

`types` kombinerer `solo` (kan spilles alene), `online` (spilles med andre over nettverket) og `party` (en gruppe som spiller sammen). `party.local` lister de nøyaktige antallene personer som kan spille på én skjerm. `party.online` lister vennegruppestørrelsene, opptil 4, som kan gå inn på nett sammen, ikke romkapasiteten. Størrelsene er nøyaktige: `[2, 4]` utelukker 3. `party` krever typen `party`, `party.online` krever `online`, og en 1 i `party.local` krever `solo`. `roomVoice: true` slår på romstemme og krever `online`.

`controller.support` er `off` (standard når `controller` utelates), `optional` eller `required`. Når den ikke er `off`, navngir `controller.type` de minste kontrollene spillet trenger:

- `any`: retninger, Confirm og Cancel. Alle kontrollere fungerer, også fjernkontroller.
- `simpler`: én analog spak, fire hovedknapper og Menu. PlayDrop-telefonkontrollere og standard spillkontrollere kvalifiserer.
- `standard`: styrekors, to klikkbare spaker, fire hovedknapper, to skulderknapper, to avtrekkere og Menu.
- `custom`: reservert for spillspesifikke telefonkontroller. Ikke tilgjengelig ennå.

Med kontrollerstøtte på må hvert deklarerte lokale antall kunne spilles med kontrollere. Les kontrollerinndata via [SDK-en](https://www.playdrop.ai/nb/create/learn/sdk). Eksisterende spill kan beholde `players` og `controllerMode`, som fortsatt fungerer, men nye spill bruker disse feltene, og én oppføring kan ikke blande begge. Hosten velger lokal eller nettbasert spilling, aldri begge. Disse deklarasjonene overlever opplastinger via Cloud, CLI og MCP, beholdte private versjoner og publisering. Tilgjengelighet avhenger også av plattformens utrulling og host-bygget.

For MCP-serveropplastinger leverer du en bygd ESM-`.mjs`/`.js`-pakke som en `SERVER`-beskrivelse og peker `server.entry` til den. Kildeprosjekter for Cloud/CLI beholder TypeScript-inngangen sin. PlayDrop leverer kjøretiden for Colyseus og server-SDK-en. Ta aldri med påloggingsopplysninger for stemmeleverandører i et spill.