Skip to main content

Tournaments

Tournaments are competitions which span a short period where opponents compete over a prize.

This document outlines the design of tournaments for Nakama server. It covers the rules for how players find tournaments, which ones they can join, when they’re allowed to submit scores, and how rewards are distributed when the tournament ends.

Rules​

Tournaments are all expressed as leaderboards with special configurations. When creating a new tournament you can set rules around its scheduling, authoritative status, and number and type of participants. Tournaments are distinguished from leaderboards by the ability to add a maximum number of score attempts an opponent can submit for each given tournament duration.

Tournaments can restrict the number of opponents allowed (i.e. First come, First serve) and enforce an optional join requirement. For example each opponent must join before they can submit scores, and only the first 10,000 opponents are allowed to join.

A tournament can also be played by opponents who are not users. For example a guild tournament can be implemented where score submissions are made by guild ID.

Scheduling​

Tournaments are created programmatically to start in the future or immediately upon creation. At creation each tournament must have a startTime (starts immediately if not set) and duration.

You can optionally set a resetSchedule and an endTime. These values allow for flexible control over how long a tournament can be played before it is reset for the next duration, and when it definitively ends. For example a tournament could be created that starts at noon each day and be played for one hour. This would be expressed with a CRON expression (0 12 * * \*) and a duration of 3600 seconds.

A tournament created with:

  • Only duration starts immediately and ends after the set duration
  • a duration and resetSchedule starts immediately and closes after the set duration, then resets and starts again on the defined schedule
  • a duration, resetSchedule, and endTime starts immediately and closes after the set duration, then resets and starts again on the defined schedule until the end time is reached

If an endTime is set, that timestamp marks the definitive end of the tournament, regardless of any resetSchedule or duration values.

Authoritative tournaments​

Tournaments can be created as either authoritative (default) or non-authoritative. To create a non-authoritative tournament, you must explicitly set the authoritative flag to false when creating the tournament, it cannot be changed later.

For authoritative tournaments, clients cannot submit scores directly to the tournament. All score submissions must be via the server runtime functions.

For non-authoritative tournaments, clients can submit scores directly to the tournament.

List tournaments​

Find tournaments which have been created on the server. Tournaments can be filtered with categories and via start and end times.

Omitting the start and end time parameters returns the ongoing and future tournaments.

Setting the end time parameter to 0 only includes tournaments with no end time set in the results.

Setting end time to a > 0 Unix timestamp acts as an upper bound and only returns tournaments that end prior to it (excluding tournaments with no end time).

Setting the start time to a > 0 Unix timestamp returns any tournaments that start at a later time than it.

Join tournament​

A tournament may need to be joined before the owner can submit scores. This operation is idempotent and will always succeed for the owner even if they have already joined the tournament.

List tournament records​

Getting the Rank Count

The record list result from calling any tournament list function includes a RankCount property which provides the total number of ranked records in the specified tournament leaderboard. This is only populated for leaderboards that are part of the rank cache (i.e. are not included in the leaderboard.blacklist_rank_cache configuration property).

Fetch a mixed list of tournament records as well as a batch of records which belong to specific owners. This can be useful to build up a leaderboard view which shows the top 100 players as well as the scores between the current user and their friends.

List tournament records around owner​

Fetch the list of tournament records around the owner.

Write tournament record​

Authoritative Leaderboards

For authoritative leaderboards, clients cannot submit scores directly. All score submissions must be via the server runtime functions.

Submit a score and optional subscore to a tournament leaderboard. If the tournament has been configured with join required this will fail unless the owner has already joined the tournament.

Delete tournament record​

Delete a tournament record by its ID.

Authoritative functions​

The runtime functions can be accessed via the server framework and enable custom logic to be used to apply additional rules to various aspects of a tournament. For example it may be required that an opponent is higher than a specific level before they’re allowed to join the tournament.

Create tournament​

Create a tournament with all it’s configuration options.

If you don’t create a tournament with a reset schedule then you must provide it with an end time.

Delete tournament​

Delete a tournament by it’s ID.

Add score attempts​

Add additional score attempts to the owner’s tournament record. This overrides the max number of score attempts allowed in the tournament for this specific owner.

Tournaments created without a defined maxNumScore have a default limit of 1,000,000 attempts.

Reward distribution​

When a tournament’s active period ends a function registered on the server will be called to pass the expired records for use to calculate and distribute rewards to owners.

To register a reward distribution function in Go use the initializer.

A simple reward distribution function which sends a persistent notification to the top ten players to let them know they’ve won and adds coins to their virtual wallets would look like:

Advanced​

Tournaments can be used to implement a league system. The main difference between a league and a tournament is that leagues are usually seasonal and incorporate a ladder or tiered hierarchy that opponents can progress on.

A league can be structured as a collection of tournaments which share the same reset schedule and duration. The reward distribution function can be used to progress opponents between one tournament and the next in between each reset schedule.

See the Tiered Leagues guide for an example.

Tournament metadata​

Each tournament and tournament record can optionally include additional data about the tournament itself, or the score being submitted and the score owner. The extra fields must be JSON encoded and submitted as the metadata.

An example use case for metadata is info about race conditions in a driving game, such as weather, which can give extra UI hints when users list records.

    {
      "surface": "wet",
      "timeOfDay": "night",
      "car": "Porsche 918 Spyder"
    }