Docs / Leaderboards & tournaments

Leaderboards & tournaments

Score tables with multiple scoring modes and time windows. Tournaments wrap leaderboards with seasonal resets, brackets, and prize distribution.

Leaderboard models

  • Monotonic - keeps the highest score submitted per player (e.g. “best lap”).
  • Cumulative - sums submissions (e.g. “total XP”).
  • Windowed - same as above but with a rolling time window (weekly / monthly) that resets automatically.

Submitting scores

game.leaderboard.submit("arena:weekly", player_id, kills)

Reading

for _, e in ipairs(game.leaderboard.top("arena:weekly", 10)) do
    print(e.rank, e.player_id, e.score)
end
local my_rank = game.leaderboard.rank("arena:weekly", player_id)
local near    = game.leaderboard.around("arena:weekly", player_id, 5)

REST

GET  /api/v1/leaderboards/:id                  Top N entries
GET  /api/v1/leaderboards/:id/around/:player   Entries around a player
POST /api/v1/leaderboards/:id                  Submit a score

Starting a board

Boards are lazily spawned on first use - the first call to submit/top/rank with a board ID starts a dedicated asobi_leaderboard_server process. There is nothing to start and nothing to configure: submit a score and the board exists.

Tournaments

A tournament wraps a leaderboard with a time window and prize pool. Players list, read and join them over the API:

GET  /api/v1/tournaments               List active tournaments
GET  /api/v1/tournaments/:id           Get tournament details
POST /api/v1/tournaments/:id/join      Join a tournament

There is no route that creates one. Listing, reading and joining are all a client can do today; a tournament is brought into existence by the release itself, which means a self-hoster does it in their own application code and a cloud tenant cannot do it at all. See the Erlang API reference.

Seasons

Seasons wrap longer lifecycles (weekly competitive, monthly events). When a season ends, leaderboards tied to it reset and archive snapshots are persisted for history queries.

Where next?