# Placares para jogos do PlayDrop

Declare placares no catalogue.json, envie pontuações com sdk.leaderboards e mostre o topo e os vizinhos do jogador. Tipos de pontuação, limites e atualizações.

Source: https://www.playdrop.ai/pt-br/create/learn/leaderboards

Os placares dão aos jogadores um motivo para jogar de novo e uma posição para compartilhar. O PlayDrop guarda a melhor pontuação de cada jogador em cada placar e a mostra no jogo.

## Declare um placar

Adicione-o ao jogo no [catalogue.json](https://www.playdrop.ai/pt-br/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`: de 3 a 64 caracteres, começando com uma letra minúscula, seguida de letras minúsculas, dígitos, `_`, `.` ou `-`.
- `scoreType` e `sort` vêm em dois pares: `INTEGER` com `DESC` (a maior vence, pontuações de 0 ou mais) ou `TIME_MS` com `ASC` (a menor vence, milissegundos positivos).
- `unitLabel` é um texto de exibição opcional.

Depois de publicada, uma chave não pode ser removida, e seu `scoreType` e seu `sort` não podem mudar. Para deixar de usar um placar, defina `"status": "RETIRED"`. Os placares precisam de um [pacote](https://www.playdrop.ai/pt-br/create/learn/packaging).

## Envie e leia pontuações

```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();
```

- As pontuações são inteiros seguros. Só uma pontuação melhor substitui o recorde.
- `top` aceita de 1 a 100 entradas e `aroundMe` de 1 a 20 de cada lado do jogador.
- `list({ includeRetired: true })` também retorna os placares aposentados.

Envie a pontuação no fim de uma partida, não a cada quadro, e só na fase `play`. Trate chamadas rejeitadas como qualquer chamada de rede; mantenha o jogo jogável.

## Convidados e modo offline

Você pode enviar sem verificar o login. Sem nenhuma sessão de jogador, um envio é resolvido sem ser armazenado. Hosts que anunciam suporte a dados no dispositivo, como os apps do PlayDrop que funcionam offline, guardam uma pontuação feita offline e a sincronizam depois; as leituras offline deles mostram só o recorde do próprio jogador, sem posição. Nos outros casos, um envio precisa de conexão.

## O que os placares não fazem

O SDK não tem regiões, reinicializações agendadas, temporadas nem prêmios semanais automáticos. Para um placar semanal, inclua a semana no seu próprio design, por exemplo com uma nova chave por temporada declarada em uma nova versão.

Relacionados: [conquistas](https://www.playdrop.ai/pt-br/create/learn/achievements), [salvamentos na nuvem](https://www.playdrop.ai/pt-br/create/learn/cloud-saves), [compartilhar uma pontuação](https://www.playdrop.ai/pt-br/create/learn/social).

## Guias relacionados

- [Conquistas](https://www.playdrop.ai/pt-br/create/learn/achievements): Declare conquistas padrão e incrementais com ícones no catalogue.json, desbloqueie-as e informe o progresso com sdk.achievements.
- [Salvamentos na nuvem](https://www.playdrop.ai/pt-br/create/learn/cloud-saves): Salve e carregue o progresso com sdk.me.appData e sdk.me.updateAppData, para convidados e jogadores logados, com as regras de gravação, prévias e modo offline.
- [catalogue.json](https://www.playdrop.ai/pt-br/create/learn/catalogue-json): Os campos do catalogue.json que os jogos do PlayDrop usam: identidade, listagem, modos de jogo, superfícies, login, Instantâneo, pré-carregamento, mídia, traduções, pontuações e servidores.