# Tulostaulut PlayDrop-peleihin

Määrittele tulostaulut catalogue.jsonissa, lähetä pisteet sdk.leaderboards-rajapinnalla ja näytä kärki ja pelaajan naapurit. Pistetyypit, rajat ja päivityssäännöt.

Source: https://www.playdrop.ai/fi/create/learn/leaderboards

Tulostaulut antavat pelaajille syyn pelata uudelleen ja sijoituksen, jonka voi jakaa. PlayDrop tallentaa jokaisen pelaajan parhaan tuloksen tulostaulua kohden ja näyttää sen pelin yhteydessä.

## Määrittele tulostaulu

Lisää se sovellukseen tiedostossa [catalogue.json](https://www.playdrop.ai/fi/create/learn/catalogue-json):

```json
{
  "leaderboards": [
    { "key": "high-score", "displayName": "High score", "description": "Most points in one run",
      "scoreType": "INTEGER", "sort": "DESC", "unitLabel": "pts" },
    { "key": "best-time", "displayName": "Fastest run", "description": "Time to reach the flag",
      "scoreType": "TIME_MS", "sort": "ASC" }
  ]
}
```

- `key`: 3–64 merkkiä, alkaa pienellä kirjaimella, jonka jälkeen pieniä kirjaimia, numeroita, `_`, `.` tai `-`.
- `scoreType` ja `sort` tulevat kahtena parina: `INTEGER` ja `DESC` (suurempi voittaa, pisteet 0 tai enemmän) tai `TIME_MS` ja `ASC` (pienempi voittaa, positiiviset millisekunnit).
- `unitLabel` on valinnainen näyttöteksti.

Julkaistua avainta ei voi poistaa, eikä sen arvoja `scoreType` ja `sort` voi muuttaa. Lopeta tulostaulun käyttö asetuksella `"status": "RETIRED"`. Tulostaulut vaativat [paketin](https://www.playdrop.ai/fi/create/learn/packaging).

## Lähetä ja lue pisteitä

```js
const result = await sdk.leaderboards.submitScore("high-score", 1200);
// { accepted, improved, previousBestScore, bestScore, rank, previousRank, bestScoreAt, leaderboard }
if (result.improved) showNewBest(result.bestScore, result.rank);

const { leaderboard } = await sdk.leaderboards.get("high-score", { top: 10, aroundMe: 3 });
// leaderboard: { definition, top, player, playerEntry, aroundPlayer }

const { leaderboards } = await sdk.leaderboards.list();
```

- Pisteet ovat turvallisia kokonaislukuja. Vain parempi tulos korvaa ennätyksen.
- `top` hyväksyy 1–100 tulosta ja `aroundMe` 1–20 tulosta pelaajan kummallakin puolella.
- `list({ includeRetired: true })` palauttaa myös käytöstä poistetut tulostaulut.

Lähetä pisteet pelikierroksen lopussa, älä joka ruudulla, ja vain `play`-vaiheessa. Käsittele hylätyt kutsut kuten minkä tahansa verkkokutsun; pidä peli pelattavana.

## Vieraat ja offline

Voit lähettää pisteitä tarkistamatta kirjautumista. Jos pelaajaistuntoa ei ole lainkaan, lähetys valmistuu tallentumatta. Laitedataa tukevat isännät, kuten offline-tilaa tukevat PlayDrop-sovellukset, säilyttävät offline-tilassa tehdyn tuloksen ja synkronoivat sen myöhemmin; offline-tilassa luettaessa ne näyttävät vain pelaajan oman ennätyksen ilman sijoitusta. Muualla lähetys vaatii verkkoyhteyden.

## Mitä tulostaulut eivät tee

SDK:ssa ei ole alueita, ajastettuja nollauksia, kausia eikä automaattisia viikkopalkintoja. Viikoittaista tulostaulua varten sisällytä viikko omaan suunnitteluusi, esimerkiksi jokaiselle kaudelle uusi avain, joka ilmoitetaan uudessa versiossa.

Liittyvät: [saavutukset](https://www.playdrop.ai/fi/create/learn/achievements), [pilvitallennukset](https://www.playdrop.ai/fi/create/learn/cloud-saves), [tuloksen jakaminen](https://www.playdrop.ai/fi/create/learn/social).

## Liittyvät oppaat

- [Saavutukset](https://www.playdrop.ai/fi/create/learn/achievements): Määrittele tavalliset ja kasvavat saavutukset kuvakkeineen catalogue.json-tiedostossa, avaa ne ja raportoi edistyminen sdk.achievements-rajapinnalla.
- [Pilvitallennukset](https://www.playdrop.ai/fi/create/learn/cloud-saves): Tallenna ja lataa edistyminen sdk.me.appData- ja updateAppData-rajapinnoilla vieraille ja kirjautuneille sekä kirjoitus-, esikatselu- ja offline-säännöt.
- [catalogue.json](https://www.playdrop.ai/fi/create/learn/catalogue-json): PlayDrop-pelien catalogue.json-kentät: tunniste, pelisivu, pelitavat, näkymät, kirjautuminen, Instant, esilataus, media, käännökset, pisteet ja palvelimet.