Skip to main content
Version: 5.7.0

Tournament

The TournamentService API allows apps to interact with brainCloud's Global Tournaments feature.

Tournaments allow developers to automatically reward players based on their performance in leaderboards. Rewards can be virtual currencies, XP, stats and more.

To create an instance of a Tournament, you first create a Tournament Template - and attach it to a Leaderboard via the Design Portal.

Once a Leaderboard has a Tournament attached its behavior changes (i.e., you need to join the tournament before you can post scores, etc.)

At the end of a Tournament cycle (i.e. period), players are sent a SYSTEM_TOURNAMENT_COMPLETE event indicating that the tournament has completed. If there is a reward, the app should claim it.

SYSTEM_TOURNAMENT_COMPLETE event

{
    "eventData": {
        "leaderboardId": "bronzeTourney",
        "versionId": 40
    },
    "createdAt": 1485634987425,
    "fromPlayerId": "",
    "toPlayerId": "06d7b728-b797-41cc-a872-00a3188e151e",
    "eventType": "SYSTEM_TOURNAMENT_COMPLETE",
    "evId": "588cfdab9911cc728ee21eae"
}

For more information on Events, see the Events API.

tip

Pro-tip: There are two fields, tRank and rank, in our tournament system. The former repesents the tournament ranking for the score (with tied tournament scores will be having the same tRank), the latter repesents the leaderboard ranking, it will be unique, so even tied scores will be given a different leaderboard rank (with the most recently posted "tied' score having a better rank).

Tournament Divisions​

Tournaments with too many players can be less enticing to players because they have a smaller chance to win. Divisions solve this problem by arbitrarily breaking smaller groups - eg. 100 players each. We call each mini-competition a Division Instance.

Divisions Instances only exist for a single tournament period. Once the challenge period is complete, players are disbursed and will join new division instances as the next tournament cycle begins.

FYI - Division instances are essentially managed leaderboards, and are given special leaderboard ids to distinguish them. The ids, for example ^D^weekly^55, include an incrementing sequence number that identity the instance.

Note - Divisions are not to be confused with Tiers. Tiers normally imply a ranking difference between players - eg. bronze, silver and gold. You can implement this notion in brainCloud using a separate division set (or simply leaderboards+tournaments) for each tier - the management of ranking players up/down is up to the developer. Ask us for implementation suggestions if you are interested.

API Summary​

Tournaments​

The following API calls are used for leaderboards with Tournaments attached:

Use the standard Leaderboard Service apis for retrieving player standings (i.e. GetGlobalLeaderboardPage, GetGlobalLeaderboardView, etc.)

Divisions​

The following API calls are specific to Divisions:

  • GetDivisionInfo - get info about the specified division set. Call instead of GetTournamentStatus() to retrieve the prize rules and scheduling status of a division.
  • JoinDivision - join a division set (will be assigned to an instance). Call instead of JoinTournament().
  • LeaveDivisionInstance - leave a division instance. Call instead of LeaveTournament().
  • GetMyDivisions - retrieves a list of the division instances that player is/has recently participated in

PostTournamentScoreUTC, ViewCurrentReward, ViewReward, and ClaimTournamentReward all work as expected for divisions.

System calls​

📄️ SysDeleteDivisionSetConfig

Deletes the division set configuration uniquely identified by the division set id, with optional, additional enforcement. NOTE: Does NOT delete any division set instance leaderboards that have currently been created, those will expire at the normal time. Does NOT prevent players from posting scores to a division set instance they are already a member of. WILL prevent new players for joining the deleted division set (JoinDivisionSet Tournament service API). WILL prevent users from querying the division info (GetDivisionInfo Tournament service API). WILL prevent Design Portal users from being able to view the rankings of the division set instance leaderboards for the deleted Division Set config.

Last updated on by Jason Liang