brainCloud’s new Global Tournaments feature is an entirely new system designed to amplify player engagement in your games.

Global Tournaments are suitable for any game where competition centres around leaderboards. In fact, in their simplest version, Global Tournaments can be thought of simply as prize rules associated with a leaderboard.

But as you will see, there is actually a whole lot more to them.



When designing Global Tournaments, we had a specific set of goals in mind.

brainCloud’s Global Tournaments should:

  • Be easy to add to apps
  • Be flexible in terms of tournament schedule, phases, rules, payouts, etc.
  • Integrate with brainCloud’s existing reward systems
  • Automate key aspects of player engagement
  • Be manageable so that entry fees, prize amounts, etc. can change over time as you iterate
  • Act as building blocks for building more complex tournament types (i.e. tiered tournaments, etc.)
  • Work within the existing brainCloud pricing tiers



Global Tournaments support the following key features:

  • Duration – support for daily, weekly, and arbitrary length tournaments (up to 14 days)
  • Phases – support for optional announcementenrollmentcompetitionbuffer and award phases
  • Flexible Prizes – Award participants any combination of virtual currencyxpplayer statsachievements and custom data
  • Entry fees – Free vs. Paid Tournaments
  • Push Notifications – automatically send configurable push notifications at key points during the tournament
  • Email Integration – send custom email notifications as well




This diagram describes the main entities involved in creating a Tournament:

  • Leaderboards are defined in the brainCloud system by entities we call Leaderboard Configs
  • To create a tournament, you attach a Tournament Template to a Leaderboard Config
  • The Tournament Template defines the rules of a tournament – entry fees, prize rules, notification templates, etc.
  • The Leaderboard Config defines how scoring works (highest score, cumulative score, etc), the rotation schedule, and also the pacing of the tournament phases.
  • Each rotation of the leaderboard is a Leaderboard Version. All scores are stored by version in Leaderboard Entry objects.


Special rules:

  • The same tournament template may be used by multiple leaderboards. This of course creates a separate tournament per leaderboard.
  • A leaderboard may also attach multiple tournament templates. This is useful for cases where you want to have both free and paid versions of a tournament, that act upon the same set of scores. (rationale: better liquidity, smaller payouts)


Tournament interactions / api

The following are the key tournament interactions to understand:

  • Get Tournament Status – returns the status of the specified tournament, and whether the player is currently enrolled in it. If the player is not enrolled, returns details of all the tournament configs associated with the leaderboard
  • Join Tournament – all tournaments must be joined before you can submit scores to them. Joining a tournament involves specifying the leaderboard that anchors the tournament, and the tCode of the tournament [template] that you are joining. An entry fee will automatically be deducted from the player’s currency balance if required.
  • Post Tournament Score – posts an score to the tournament leaderboard. Note that you must pass in the epoch time that the game round started in, to ensure that the score is eligible. Note that there are several versions of this operation (see the API for details).
  • View Current Reward – returns the player’s standing in the currently active tournament, and the reward they can expect to receive if they keep this rank.
  • View Reward – returns the players reward for a completed tournament, and whether it has already been claimed. Will return an error if the player is not enrolled in the tournament.
  • Check For Events – query the brainCloud events queue to see if any Tournament Completion events have arrived
  • Claim Tournament Reward – claims the rewards for a completed tournament, incrementing appropriate player balances (currencies, etc.).

For more information on these interactions, see the Tournament API.


Phases and States

Tournament States are used to organize the larger tournament lifecycle. They determine when tournaments are active, processing award calculations, and available for award clams.

Tournament Phases help to micro-manage when players can join tournaments, post scores, etc. throughout the Active tournament state.

The following diagram summarizes the relationship between brainCloud tournament states and phases:

Note that brainCloud doesn’t explicitly tell you the phase it is in – instead, it gives you information as to when registration starts and ends, when play starts and ends, etc.


Events and Notifications

A key goal of brainCloud’s Global Tournaments system is to automate the tournaments interactions with players. As such, the system:

  • Automatically rotates and cycles through tournament states and phases as per the schedule defined
  • Send events to players when the tournament has completed
  • Optionally sends push notifications and/or emails
    • When a new tournament opens for registration (enrollment) – sent to previous tournament participants
    • When a new tournament opens for play (competition) – sent to previous and currently registered participants
    • When a tournament’s competition phase is close to ending – sent to current participants
    • When another player beats their tournament score, bumping them down a rank – sent to current participants within 10 ranks of the player who posted the score
    • When a tournament completes and they’re awards are ready to be claimed – sent to current participants. The system also sends an Event to the player’s event queue.

Note that you shouldn’t blindly configure all notifications – especially the email-based notifications. Some recommendations:

  • Obviously, do not configure both Tournament Registration start and Tournament Play start if your tournament doesn’t have an exclusive registration period, or your players will get two back-to-back notifications, and be annoyed.
  • Be careful about configuring Email-based notifications – we’ve included the trigger points, but for most cases we would recommend that you mostly use them to announce that a tournament is complete and that the player should come collect their prize. It’s also a handy opportunity to include info on other game offers, bonuses items to increase scores, etc.
  • Be aware that brainCloud does not yet support automated unsubscribes (coming soon)


Special: Scoring notifications

There are two types of designers. Designers who think that scoring notifications are cool, and those that think they could get annoying very quickly. And they are both right.

To add the engagement of scoring notifications, hopefully without overwhelming the player, we’ve added the following rules:

  • We’ll only send a player one scoring notification per 24-hour period

The are two additional rules that affect this:

  • If you post a new score, we reset the notification clock. This means that engaged players will receive more than one notification in a 24 hour period, because they’re actually responding to them.
  • We won’t send the player a score update until at least 30 minutes after their last posted score (i.e. you don’t want to receive a push notification immediately after exiting the game)


Bonus Features: Auto Join and Auto Reward

Global Tournaments offer an incredible way to increase engagement and monetization with your players – but what if you are just looking for a quick way to automatically add rewards to your weekly leaderboards – without code changes?

Look no further – brainCloud has two new features that allow you to automate the key portions of the tournament processing:

  • Auto Join – Enables players to automatically join the tournament associated with a leaderboard, simply by posting a score to it (via the standard leaderboard PostScore method). Note that this only works for leaderboards that have one-and-only-one tournament associated with them – and that tournament must be free.
  • Auto Claim – Causes tournament rewards to be automatically claimed by players during login. Note that the [x] Enable Tournament Auto Claim check at login compatibility flag must also be enabled on the Design | Core App Info | Advanced page of the portal

Note – although we provide the Auto Join and Auto Claim features for convenience, in most cases we would definitely recommend that you implement the full tournament API. A key benefit to tournaments is engaging with your players – getting them excited about what they can win and adding that extra flourish as they claim their prizes. Auto Join and Auto Claim hide all that – minimizing the opportunity for extra player engagement.


Features Availability and Billing Notes

Global Tournaments are available across all brainCloud subscription plans.

The basic API billing rules are in effect – 1 API count per API call, 1 API count per Push Notification, 1 API count per Email Sent

In addition, the following counts are added to offset the overheads of automated tournaments:

  • Awards Calculation – At the end of the tournament, 1 Bulk API Count per participant is charged to cover the CPU load of processing results and sending events to the players
  • PostTournamentScoreWithResults() – adds 1 Bulk API count to cover the overhead of comparing the players previous and current tournament results, and determining whether to send notifications to displaced players. As compensation, however, returns the updated tournament results (essentially GetGlobalLeaderboardView()), hopefully saving the app an API call in return.
  • Auto Claim – if the Auto-Claim feature is enabled, 0.5 Bulk API Counts are added to each Authentication()