# catalogue.json: PlayDrop-pelin metatiedot ja lokalisointi

Viite pelin nimille, kuvauksille, lajitunnisteille, pelisivun kuville ja videoille, käännöksille ja valinnaiselle server-kentälle PlayDrop Connectorissa.

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

[PlayDrop Connector](https://www.playdrop.ai/fi/create/connectors) lähettää `catalogue.json`-metatietosi pelitiedostojen mukana; komentorivityökalua ei tarvita. PlayDrop Cloud ylläpitää näitä metatietoja Studio-peleille.

## Täydellinen yksityinen lataus komennolla prepare_catalogue_upload

Tämä on täydellinen `prepare_catalogue_upload`-pyyntö uudelle yksityiselle pelille. Korvaa esimerkin HTML rakentamallasi pelillä ja käytä yksilöllistä `requestId`-arvoa jokaiselle aiotulle lataukselle. `catalogue`-objekti on tiedoston `catalogue.json` sisältö; `files` ja `expectedCurrentVersion` kuuluvat työkalupyyntöön, tuon objektin ulkopuolelle.

```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`-arvon on vastattava täsmälleen jotakin `files[].path`-arvoa. Jos `file` jätetään pois, merkintä käyttää oletuksena arvoa `<name>.html`, ei `index.html`. `surfaceTargets` on objekti, jossa on totuusarvot `desktop`, `mobileLandscape` ja `mobilePortrait`; ota käyttöön vähintään yksi testaamasi pinta. Ilmoita versio ja näkyvyys selvästi. Esimerkki käyttää upotettua tekstitiedostoa; liitteet tai allekirjoitetut tavulataukset voivat käyttää samaa polkua.

Valmistelun jälkeen lähetä pyydetyt tiedostotavut ja kutsu `complete_catalogue_upload` samalla `requestId`-arvolla. Avaa yksityinen versio testataksesi sitä. Päivitystä varten lue `list_games`, säilytä sama `name`, anna uusi `version` ja täysi tilannekuva ja aseta `expectedCurrentVersion[name]` palvelimen palauttamaan nykyiseen julkiseen versioon (tai arvoon `null`, jos sellaista ei ole). Se on ristiriitatarkistus, ei ladattavan version arvo. Yritä keskeytyneet lataukset uudelleen alkuperäisellä pyynnön tunnuksella. Julkaise testattu säilytetty versio komennolla `publish_game_version`, kun olet valmis.

## Vanha yhden pelin yhteensopivuusesimerkki

Alla oleva esimerkki on vanha yhden pelin muoto. Täydet katalogilataukset tukevat myös useita pelejä, resursseja, paketteja ja spec-määrityksiä; pyydä connectorilta nykyinen skeema. Jokainen päivitys antaa täyden tilannekuvan selvällä näkyvyydellä ja versiolla. Pois jätettyjä katalogin kohteita ei poisteta.

Pidä pienaakkosinen slug vakaana päivittäessäsi. Lisää tarvittaessa näyttönimi, tarkka kuvaus, ohjaimet, lähdekieli ja tunnetut tunnisteet. Alla oleva esimerkki käyttää olemassa olevaa tasohyppelylajin tunnistetta.

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

## Tuetut kentät ja rajat

`name`: 1–100 pientä kirjainta, numeroa tai yhdysmerkkiä, alkaen kirjaimella tai numerolla. `displayName`: ei-tyhjä nimi. `subtitle`: enintään 120 merkkiä. `description`: enintään 3 000 merkkiä Markdownia, ilman H1-otsikoita, upotettua mediaa tai taulukoita. `inspirationPrompt`: enintään 400 merkkiä yksirivistä pelkkää tekstiä. Tekstirajat laskevat JavaScriptin UTF-16-koodiyksiköt.

Valinnaisia kenttiä ovat `controls`, `releaseNotes`, `makingOf`, `emoji`, `color`, `sourceRepository`, `license`, `tags`, `sourceLocale`, `listingLocalizations`, `listingMedia` ja `server`. Tunnisteet käyttävät olemassa olevia `group-slug/tag-slug`-viitteitä, enintään 20 yksilöllistä tunnistetta. `server` luettelee ladatun `server.js`-tiedoston Colyseus-huoneet, esimerkiksi `"server": { "rooms": ["game"] }`; katso [server SDK](https://www.playdrop.ai/fi/create/learn/server-sdk). Pyydä connectorilta nykyiset hyväksytyt lisenssiarvot ja täydet kenttäsäännöt ennen julkaisua. Valinnaiset natiivisovellusvihjeet: `prefetch` luettelee ladatut tiedostot, jotka PlayDropin iOS-, macOS- ja Android-sovellukset voivat ladata ennen pelaamista, esimerkiksi `"prefetch": { "required": ["game.js"], "optional": ["music.mp3"] }` (aloitussivu sisältyy aina), ja `"offlineSupported": true` antaa näiden sovellusten tarjota pelin offline-tilassa, kun sen vaaditut tiedostot on tallennettu. Virheelliset arvot ohitetaan eivätkä koskaan estä latausta; verkkosivustot lataavat pelit tavalliseen tapaan.

Instant-pelit: aseta `"instant": true`, kun peli on pelattavissa 2 sekunnissa enintään 10 MB:n käynnistystiedostoista (aloitussivu sekä `prefetch.required` tai kaikki ladatut tiedostot, jos mitään ei ole lueteltu). Instant-pelit saavat salamamerkin ja pelataan PlayDropin puhelinsovellusten Instant-syötteessä. Laita syvemmät kentät ja lisäsisältö kohtaan `prefetch.optional`, viimeistele shaderien käännös ja muu lämmittely ennen `ready()`-kutsua, tee esikatselusta pelitilanne otsikkoruudun sijaan ja salli vieraat (`authMode` `OPTIONAL` tai `NONE`), jotta kaikki näkevät pelin syötteessä. PlayDrop tarkistaa koon latauksessa ja poistaa merkin versioilta, jotka käynnistyvät puhelimissa hitaasti; peli, joka ei yllä rajaan, julkaistaan silti.

## Pelisivun kuvat ja videot

Lataa pelisivun media tiedostoina `index.html`-tiedoston viereen polun mukaan nimettynä: `listing/icon.png`, `listing/hero-landscape.png` (16:9) ja `listing/hero-portrait.png` (9:16), joissa pelin nimi on kuvituksessa, kuvakaappaukset kuten `listing/screenshots/landscape/0.png` sekä videot `listing/videos/landscape/0.mp4` (traileri) ja `listing/videos/portrait/0.mp4` (mobiilitiisteri). Videot toistetaan äänettöminä pelikorteissa ja pelisivulla, traileri tietokoneilla ja televisiossa ja tiisteri puhelimilla, joten ne ovat nopein tapa näyttää pelattavuus ja saada ensimmäinen pelikerta. Kuvat ovat PNG ja videot MP4.

## Käännä pelisivu tarkasti

Julkaise aina englanti sekä oma kielesi, jos se on eri. Aseta `sourceLocale` alkuperäiseksi kieleksi. `listingLocalizations` tukee englantia, ranskaa, saksaa, espanjaa, brasilianportugalia, indonesiaa, japania, koreaa, perinteistä kiinaa ja yksinkertaistettua kiinaa. Jokainen käännös tarvitsee `locale` ja `displayName`; kun lataat sen lähteensä kanssa, PlayDrop täyttää `sourceHash`-arvon. Lataa käännetty kuvitus polkuun `listing/locales/<locale>/`, esimerkiksi `listing/locales/fr/hero-landscape.png` ranskankielisellä nimellä; se yhdistetään käännökseensä automaattisesti. Päivitä käännökset lähteen muutosten jälkeen. Pelisivun kääntäminen ei käännä itse peliä.

## Pelaajat, ryhmät ja ohjaimet

Ilmoita, miten peliäsi pelataan, kentillä `types`, `party`, `controller` ja `roomVoice` jokaisessa pelimerkinnässä:

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

`types` yhdistää `solo` (pelattavissa yksin), `online` (pelataan muiden kanssa verkossa) ja `party` (ryhmä pelaa yhdessä). `party.local` luettelee tarkat ihmismäärät, jotka voivat pelata yhdellä ruudulla; `party.online` luettelee ystäväryhmien koot, enintään 4, jotka voivat siirtyä verkkoon yhdessä, ei huoneen kapasiteettia. Koot ovat tarkkoja: `[2, 4]` sulkee pois 3:n. `party` vaatii `party`-tyypin, `party.online` vaatii `online`-tyypin, ja 1 kohdassa `party.local` vaatii `solo`-tyypin. `roomVoice: true` ottaa huoneen puheen käyttöön ja vaatii `online`-tyypin.

`controller.support` on `off` (oletus, kun `controller` jätetään pois), `optional` tai `required`. Kun se ei ole `off`, `controller.type` nimeää pelin tarvitsemat vähimmäisohjaimet:

- `any`: suunnat, Confirm ja Cancel; jokainen ohjain toimii, myös kaukosäätimet.
- `simpler`: yksi analogitikku, neljä etupainiketta ja Menu; PlayDropin puhelinohjaimet ja tavalliset peliohjaimet kelpaavat.
- `standard`: D-pad, kaksi painettavaa tikkua, neljä etupainiketta, kaksi olkapainiketta, kaksi liipaisinta ja Menu.
- `custom`: varattu pelikohtaisille puhelinohjaimille; ei vielä saatavilla.

Kun ohjaintuki on päällä, jokainen ilmoitettu paikallinen määrä on voitava pelata ohjaimilla; lue ohjainsyöte [SDK:n](https://www.playdrop.ai/fi/create/learn/sdk) kautta. Olemassa olevat pelit voivat säilyttää `players` ja `controllerMode`, jotka toimivat yhä, mutta uudet pelit käyttävät näitä kenttiä, eikä yksi merkintä voi sekoittaa molempia. Isäntä valitsee paikallisen tai verkkopelin, ei koskaan molempia. Nämä ilmoitukset säilyvät Cloud-, CLI- ja MCP-latauksissa, säilytetyissä yksityisissä versioissa ja julkaisussa. Saatavuus riippuu myös alustan käyttöönotosta ja isäntäversiosta.

MCP-palvelinlatauksissa anna rakennettu ESM-paketti `.mjs`/`.js` `SERVER`-kuvaajana ja osoita `server.entry` siihen. Cloud-/CLI-lähdeprojektit säilyttävät TypeScript-aloituspisteensä. PlayDrop tarjoaa Colyseus- ja server SDK -ajoympäristön; älä koskaan sisällytä puheenpalveluntarjoajan tunnuksia peliin.